Skip to content

FE-2331 / FE-2218 feat(account-ui, billing-web): hosted composables, own-origin session and v1 surfaces - #17799

Merged
dante01yoon merged 4 commits into
jaewon/fe-2331-plans-payment-methods-readersfrom
jaewon/fe-2331-account-ui-hosted-composables
Sep 16, 2026
Merged

dante01yoon merged 4 commits into
jaewon/fe-2331-plans-payment-methods-readersfrom
jaewon/fe-2331-account-ui-hosted-composables

Conversation

@dante01yoon

@dante01yoon dante01yoon commented Sep 16, 2026 •

Copy link
Copy Markdown
Collaborator

Linear FE-2331.

Stacked on #17798 (readers); carries #17797 (previewSubscribe, now on main) until #17798 lands. #17807 (billing-web own-origin session + sign-in) and #17809 (billing-web /v1 surfaces) were squash-merged into this branch, so this PR is the whole Phase 8 view layer: account-ui composables, the billing-web session/sign-in, and the subscription / payment-method surfaces.

Why

The plans catalog, the saved cards and the subscription quote are the three
reads the hosted billing surfaces are built on, and the core now exposes all
three. Nothing in the view layer could reach them: BillingClient carried only
the balance, capability and status readers, so a host wanting a price had to
call the core directly and invent its own loading, failure and cancellation
handling per screen.

How

  • BillingClient gains plans and paymentMethods; disposeBillingClient
    disposes both, so a sign-out or workspace switch cannot leave a catalog or a
    card list serving the previous scope.
  • usePlans and usePaymentMethods follow useCredits: seeded from the
    reader's snapshot, immediate by default, and a failed refresh keeps the last
    good value beside the failure rather than blanking the screen.
    usePaymentMethods also exposes defaultMethod and invalidateAndRefresh,
    for a host coming back from the payment portal where a card was added or
    removed.
  • usePreviewSubscribe is on-demand and single-flight: each quote aborts the
    one before it through an AbortController, and only the latest settles into
    preview/failure, so a slow price for a plan the user has moved off never
    lands on screen.
  • The app composition root builds both readers and adds them to dispose(),
    keeping the two scope-holder lists in step. Commands stay unwired here.

AS-IS / TO-BE

No UI change. These are headless composables; nothing renders them yet.

Testing

usePlans, usePaymentMethods and usePreviewSubscribe tests run against the
real core over the shared billing harness. Both the abort guard and the
payment-methods invalidation were verified to fail when removed. A table in
createBillingSdk.test.ts asserts every reader stops serving the disposed
scope.

Where this sits in the plan

Billing SDK track FE-2210 (implementation plan V2). Hybrid model: top-up in-app, subscription management / invoices / payment methods on the hosted billing app.

Phase Item Ticket Status
1-2 Session core, transport, readers FE-2211/2212/2213 merged
3 Operation lifecycle, commands, eight-state projection FE-2227/2214/2223 merged (#17655)
4 @comfyorg/account-ui composables + CheckoutSteps FE-2215 merged (#17662, #17663)
5 slice 1 Top-up through the SDK behind billing_sdk_topup_enabled FE-2216 merged (#17665)
rollout C hosted_billing_destination server flag read by the host FE-2218 merged (#17716)
rollout C hostedDestination port on the lifecycle, value on operation state FE-2210/2218 open (#17783)
7 prep Scope-source port + credentialed transport (BFF / cookie hosts) FE-2218 merged (#17782)
7 prep @comfyorg/account → @comfyorg/account-core rename FE-2218 local, opens after #17783 and #17794
7 prep billing-contract route builder + return_to registry FE-2218 merged (#17795)
3A-3 Workshop adapter over createHostedTopupCheckout FE-2214 merged (#17793)
8 core previewSubscribe command FE-2331 merged (#17797)
8 core Plans + saved payment-methods readers FE-2331 open (#17798)
8 ui account-ui composables (usePlans, usePaymentMethods, usePreviewSubscribe) FE-2331 this PR
7 billing-web own-origin session, sign-in, SDK composition FE-2218 this PR (was #17807)
8 ui billing-web /v1 entry routing + subscription / payment-method surfaces FE-2331 this PR (was #17809)
7 npm publish (ingest-types, account-core, billing-contract), Platform install, billing-web live top-up FE-2218 todo
6 Contract tests + live E2E per flow × consumer FE-2217 todo
5 slice 2 Subscription flows through the SDK FE-2216 todo (plan-change decision)
follow-up One needsCustomerAttention predicate (from the #17665 review) FE-2216 merged (#17792)
follow-up Opaque BillingServerCode (from the #17656 review) FE-2227 open (#17794)
follow-up useCredits clears on SUPERSEDED (from the #17799 review) FE-2215 open (#17824)
flowchart LR
  P3["Phase 3 core lifecycle (merged)"]
  P4["Phase 4 account-ui (merged)"]
  P5["Phase 5 slice 1 top-up flag (merged)"]
  FC["PR 17716 hosted_billing_destination flag (merged)"]
  HD["PR 17783 hostedDestination port"]
  SS["PR 17782 scope-source port + credentialed transport"]
  RN["account-core rename"]
  RB["billing-contract route builder + return_to"]
  WS["Workshop adapter"]
  P8PV["previewSubscribe command"]
  P8RD["plans + payment-methods readers"]
  P8["account-ui hosted composables"]
  BWS["billing-web session + sign-in"]
  BWV["billing-web /v1 surfaces"]
  PUB["npm publish account-core / billing-contract"]
  P7["Phase 7 host proof: Platform + billing-web live"]
  P6["Phase 6 evidence"]
  S2["Phase 5 slice 2 subscription"]
  FU9["customer-attention predicate"]
  FU11["opaque BillingServerCode"]
  FU12["useCredits clears on SUPERSEDED"]
  P3 --> HD
  FC --> HD
  HD --> RB
  P3 --> SS
  SS --> P7
  RB --> P7
  P3 --> RN
  RN --> PUB
  RB --> PUB
  PUB --> P7
  P3 --> P8PV
  P3 --> P8RD
  P8PV --> P8
  P8RD --> P8
  P4 --> P8
  P8 --> S2
  P8 --> BWS
  BWS --> BWV
  RB --> BWV
  BWV --> P7
  P5 --> P6
  P5 --> WS
  P5 --> FU9
  P3 --> FU11
  P4 --> FU12
  style P3 fill:#d4edda,stroke:#155724
  style P4 fill:#d4edda,stroke:#155724
  style P5 fill:#d4edda,stroke:#155724
  style FC fill:#d4edda,stroke:#155724
  style SS fill:#d4edda,stroke:#155724
  style RB fill:#d4edda,stroke:#155724
  style WS fill:#d4edda,stroke:#155724
  style FU9 fill:#d4edda,stroke:#155724
  style P8PV fill:#d4edda,stroke:#155724
  style P8 stroke:#0366d6,stroke-width:4px
  style BWS stroke:#0366d6,stroke-width:4px
  style BWV stroke:#0366d6,stroke-width:4px
Loading

@dante01yoon dante01yoon added needs-backport Fix/change that needs to be cherry-picked to the current feature freeze branch core/1.54 Backport PRs for core 1.54 cloud/1.54 Backport PRs for cloud 1.54 labels Sep 16, 2026
@coderabbitai

coderabbitai Bot commented Sep 16, 2026 •

Copy link
Copy Markdown
Contributor

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 8682cd47-b878-4a97-afa8-f71d51d686bf

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review

Comment @coderabbitai help to get the list of available commands.

@github-actions

github-actions Bot commented Sep 16, 2026 •

Copy link
Copy Markdown
Contributor

🌐 Website E2E

Tip

All tests passed.

Status ✅ Passed
Report View Report

🎨 Storybook: ✅ Built — View Storybook

Details

⏰ Completed at: 09/16/2026, 12:25:28 PM UTC

Links

🎭 Playwright: ✅ 2016 passed, 0 failed · 2 flaky

📊 Browser Reports
  • chromium: View Report (✅ 1995 / ❌ 0 / ⚠️ 2 / ⏭️ 13)
  • chromium-2x: View Report (✅ 2 / ❌ 0 / ⚠️ 0 / ⏭️ 0)
  • chromium-0.5x: View Report (✅ 1 / ❌ 0 / ⚠️ 0 / ⏭️ 0)
  • mobile-chrome: View Report (✅ 18 / ❌ 0 / ⚠️ 0 / ⏭️ 0)

📦 Bundle Size

⏳ Size data collection in progress…

⚡ Performance Report

canvas-idle: · 60.0 avg FPS · 59.7 P5 FPS ✅ (target: ≥52) · 0ms TBT · 68.2 MB heap
canvas-mouse-sweep: · 60.0 avg FPS · 59.9 P5 FPS ✅ (target: ≥52) · 0ms TBT · 64.2 MB heap
canvas-zoom-sweep: · 60.0 avg FPS · 59.7 P5 FPS ✅ (target: ≥52) · 0ms TBT · 61.2 MB heap
dom-widget-clipping: · 60.0 avg FPS · 59.9 P5 FPS ✅ (target: ≥52) · 0ms TBT · 76.6 MB heap
large-graph-idle: · 60.0 avg FPS · 59.5 P5 FPS ✅ (target: ≥52) · 0ms TBT · 79.3 MB heap
large-graph-pan: · 60.0 avg FPS · 59.7 P5 FPS ✅ (target: ≥52) · 0ms TBT · 73.9 MB heap
large-graph-zoom: · 60.0 avg FPS · 59.7 P5 FPS ✅ (target: ≥52) · 0ms TBT · 71.0 MB heap
legacy-node-drag: · 60.0 avg FPS · 59.7 P5 FPS ✅ (target: ≥52) · 0ms TBT · 86.2 MB heap
minimap-idle: · 60.0 avg FPS · 59.7 P5 FPS ✅ (target: ≥52) · 0ms TBT · 80.6 MB heap
subgraph-dom-widget-clipping: · 60.0 avg FPS · 59.9 P5 FPS ✅ (target: ≥52) · 0ms TBT · 72.7 MB heap
subgraph-idle: · 60.0 avg FPS · 59.7 P5 FPS ✅ (target: ≥52) · 0ms TBT · 65.1 MB heap
subgraph-mouse-sweep: · 60.0 avg FPS · 59.9 P5 FPS ✅ (target: ≥52) · 0ms TBT · 68.5 MB heap
subgraph-transition-enter: · 60.0 avg FPS · 59.5 P5 FPS ✅ (target: ≥52) · 159ms TBT · 98.5 MB heap
viewport-pan-sweep: · 60.0 avg FPS · 59.7 P5 FPS ✅ (target: ≥52) · 0ms TBT · 74.2 MB heap
vue-large-graph-idle: · 56.2 avg FPS · 59.5 P5 FPS ✅ (target: ≥52) · 0ms TBT · 184.1 MB heap
vue-large-graph-pan: · 55.4 avg FPS · 59.7 P5 FPS ✅ (target: ≥52) · 76ms TBT · 163.0 MB heap
vue-node-resize-workload: · 57.1 avg FPS · 59.7 P5 FPS ✅ (target: ≥52) · 291ms TBT · 170.7 MB heap
vue-zoom-out-idle: · 55.4 avg FPS · 59.7 P5 FPS ✅ (target: ≥52) · 0ms TBT · 174.2 MB heap
workflow-execution: · 60.0 avg FPS · 59.9 P5 FPS ✅ (target: ≥52) · 0ms TBT · 63.9 MB heap

ℹ️ No baseline found — significance unavailable.

Absolute values
Metric Value
canvas-idle: avg frame time 17ms
canvas-idle: p95 frame time 17ms
canvas-idle: layout duration 0ms
canvas-idle: style recalc duration 8ms
canvas-idle: layout count 0
canvas-idle: style recalc count 7
canvas-idle: task duration 592ms
canvas-idle: script duration 13ms
canvas-idle: TBT 0ms
canvas-idle: heap used 68.2 MB
canvas-idle: DOM nodes -263
canvas-idle: event listeners -155
canvas-mouse-sweep: avg frame time 17ms
canvas-mouse-sweep: p95 frame time 17ms
canvas-mouse-sweep: layout duration 5ms
canvas-mouse-sweep: style recalc duration 36ms
canvas-mouse-sweep: layout count 14
canvas-mouse-sweep: style recalc count 81
canvas-mouse-sweep: task duration 961ms
canvas-mouse-sweep: script duration 180ms
canvas-mouse-sweep: TBT 0ms
canvas-mouse-sweep: heap used 64.2 MB
canvas-mouse-sweep: DOM nodes -263
canvas-mouse-sweep: event listeners -169
canvas-zoom-sweep: avg frame time 17ms
canvas-zoom-sweep: p95 frame time 17ms
canvas-zoom-sweep: layout duration 1ms
canvas-zoom-sweep: style recalc duration 19ms
canvas-zoom-sweep: layout count 6
canvas-zoom-sweep: style recalc count 32
canvas-zoom-sweep: task duration 421ms
canvas-zoom-sweep: script duration 16ms
canvas-zoom-sweep: TBT 0ms
canvas-zoom-sweep: heap used 61.2 MB
canvas-zoom-sweep: DOM nodes 75
canvas-zoom-sweep: event listeners 20
dom-widget-clipping: avg frame time 17ms
dom-widget-clipping: p95 frame time 17ms
dom-widget-clipping: layout duration 0ms
dom-widget-clipping: style recalc duration 9ms
dom-widget-clipping: layout count 0
dom-widget-clipping: style recalc count 11
dom-widget-clipping: task duration 487ms
dom-widget-clipping: script duration 176ms
dom-widget-clipping: TBT 0ms
dom-widget-clipping: heap used 76.6 MB
dom-widget-clipping: DOM nodes 18
dom-widget-clipping: event listeners 2
large-graph-idle: avg frame time 17ms
large-graph-idle: p95 frame time 17ms
large-graph-idle: layout duration 0ms
large-graph-idle: style recalc duration 7ms
large-graph-idle: layout count 0
large-graph-idle: style recalc count 5
large-graph-idle: task duration 717ms
large-graph-idle: script duration 40ms
large-graph-idle: TBT 0ms
large-graph-idle: heap used 79.3 MB
large-graph-idle: DOM nodes -248
large-graph-idle: event listeners -167
large-graph-pan: avg frame time 17ms
large-graph-pan: p95 frame time 17ms
large-graph-pan: layout duration 0ms
large-graph-pan: style recalc duration 12ms
large-graph-pan: layout count 0
large-graph-pan: style recalc count 66
large-graph-pan: task duration 1723ms
large-graph-pan: script duration 904ms
large-graph-pan: TBT 0ms
large-graph-pan: heap used 73.9 MB
large-graph-pan: DOM nodes -251
large-graph-pan: event listeners -167
large-graph-zoom: avg frame time 17ms
large-graph-zoom: p95 frame time 17ms
large-graph-zoom: layout duration 14ms
large-graph-zoom: style recalc duration 11ms
large-graph-zoom: layout count 60
large-graph-zoom: style recalc count 60
large-graph-zoom: task duration 1860ms
large-graph-zoom: script duration 845ms
large-graph-zoom: TBT 0ms
large-graph-zoom: heap used 71.0 MB
large-graph-zoom: DOM nodes 0
large-graph-zoom: event listeners 9
legacy-node-drag: avg frame time 17ms
legacy-node-drag: p95 frame time 17ms
legacy-node-drag: layout duration 0ms
legacy-node-drag: style recalc duration 5ms
legacy-node-drag: layout count 0
legacy-node-drag: style recalc count 40
legacy-node-drag: task duration 2074ms
legacy-node-drag: script duration 1049ms
legacy-node-drag: TBT 0ms
legacy-node-drag: heap used 86.2 MB
legacy-node-drag: DOM nodes 0
legacy-node-drag: event listeners 188
minimap-idle: avg frame time 17ms
minimap-idle: p95 frame time 17ms
minimap-idle: layout duration 0ms
minimap-idle: style recalc duration 3ms
minimap-idle: layout count 0
minimap-idle: style recalc count 3
minimap-idle: task duration 687ms
minimap-idle: script duration 41ms
minimap-idle: TBT 0ms
minimap-idle: heap used 80.6 MB
minimap-idle: DOM nodes -255
minimap-idle: event listeners -73
subgraph-dom-widget-clipping: avg frame time 17ms
subgraph-dom-widget-clipping: p95 frame time 17ms
subgraph-dom-widget-clipping: layout duration 0ms
subgraph-dom-widget-clipping: style recalc duration 11ms
subgraph-dom-widget-clipping: layout count 0
subgraph-dom-widget-clipping: style recalc count 46
subgraph-dom-widget-clipping: task duration 435ms
subgraph-dom-widget-clipping: script duration 150ms
subgraph-dom-widget-clipping: TBT 0ms
subgraph-dom-widget-clipping: heap used 72.7 MB
subgraph-dom-widget-clipping: DOM nodes 18
subgraph-dom-widget-clipping: event listeners 7
subgraph-idle: avg frame time 17ms
subgraph-idle: p95 frame time 17ms
subgraph-idle: layout duration 0ms
subgraph-idle: style recalc duration 9ms
subgraph-idle: layout count 0
subgraph-idle: style recalc count 9
subgraph-idle: task duration 557ms
subgraph-idle: script duration 12ms
subgraph-idle: TBT 0ms
subgraph-idle: heap used 65.1 MB
subgraph-idle: DOM nodes -277
subgraph-idle: event listeners -200
subgraph-mouse-sweep: avg frame time 17ms
subgraph-mouse-sweep: p95 frame time 17ms
subgraph-mouse-sweep: layout duration 6ms
subgraph-mouse-sweep: style recalc duration 30ms
subgraph-mouse-sweep: layout count 18
subgraph-mouse-sweep: style recalc count 77
subgraph-mouse-sweep: task duration 835ms
subgraph-mouse-sweep: script duration 125ms
subgraph-mouse-sweep: TBT 0ms
subgraph-mouse-sweep: heap used 68.5 MB
subgraph-mouse-sweep: DOM nodes -276
subgraph-mouse-sweep: event listeners -201
subgraph-transition-enter: avg frame time 17ms
subgraph-transition-enter: p95 frame time 17ms
subgraph-transition-enter: layout duration 14ms
subgraph-transition-enter: style recalc duration 31ms
subgraph-transition-enter: layout count 5
subgraph-transition-enter: style recalc count 15
subgraph-transition-enter: task duration 1016ms
subgraph-transition-enter: script duration 35ms
subgraph-transition-enter: TBT 159ms
subgraph-transition-enter: heap used 98.5 MB
subgraph-transition-enter: DOM nodes 13587
subgraph-transition-enter: event listeners 2385
viewport-pan-sweep: avg frame time 17ms
viewport-pan-sweep: p95 frame time 17ms
viewport-pan-sweep: layout duration 0ms
viewport-pan-sweep: style recalc duration 42ms
viewport-pan-sweep: layout count 0
viewport-pan-sweep: style recalc count 249
viewport-pan-sweep: task duration 6481ms
viewport-pan-sweep: script duration 3001ms
viewport-pan-sweep: TBT 0ms
viewport-pan-sweep: heap used 74.2 MB
viewport-pan-sweep: DOM nodes -247
viewport-pan-sweep: event listeners -134
vue-large-graph-idle: avg frame time 18ms
vue-large-graph-idle: p95 frame time 17ms
vue-large-graph-idle: layout duration 0ms
vue-large-graph-idle: style recalc duration 0ms
vue-large-graph-idle: layout count 0
vue-large-graph-idle: style recalc count 0
vue-large-graph-idle: task duration 17633ms
vue-large-graph-idle: script duration 309ms
vue-large-graph-idle: TBT 0ms
vue-large-graph-idle: heap used 184.1 MB
vue-large-graph-idle: DOM nodes -6542
vue-large-graph-idle: event listeners -7479
vue-large-graph-pan: avg frame time 18ms
vue-large-graph-pan: p95 frame time 17ms
vue-large-graph-pan: layout duration 0ms
vue-large-graph-pan: style recalc duration 24ms
vue-large-graph-pan: layout count 0
vue-large-graph-pan: style recalc count 170
vue-large-graph-pan: task duration 22054ms
vue-large-graph-pan: script duration 985ms
vue-large-graph-pan: TBT 76ms
vue-large-graph-pan: heap used 163.0 MB
vue-large-graph-pan: DOM nodes -6542
vue-large-graph-pan: event listeners -7473
vue-node-resize-workload: avg frame time 17ms
vue-node-resize-workload: p95 frame time 17ms
vue-node-resize-workload: layout duration 26ms
vue-node-resize-workload: style recalc duration 83ms
vue-node-resize-workload: layout count 20
vue-node-resize-workload: style recalc count 20
vue-node-resize-workload: task duration 5674ms
vue-node-resize-workload: script duration 116ms
vue-node-resize-workload: TBT 291ms
vue-node-resize-workload: heap used 170.7 MB
vue-node-resize-workload: DOM nodes -6542
vue-node-resize-workload: event listeners -7477
vue-zoom-out-idle: avg frame time 18ms
vue-zoom-out-idle: p95 frame time 17ms
vue-zoom-out-idle: layout duration 0ms
vue-zoom-out-idle: style recalc duration 0ms
vue-zoom-out-idle: layout count 0
vue-zoom-out-idle: style recalc count 0
vue-zoom-out-idle: task duration 8671ms
vue-zoom-out-idle: script duration 146ms
vue-zoom-out-idle: TBT 0ms
vue-zoom-out-idle: heap used 174.2 MB
vue-zoom-out-idle: DOM nodes 0
vue-zoom-out-idle: event listeners -12
workflow-execution: avg frame time 17ms
workflow-execution: p95 frame time 17ms
workflow-execution: layout duration 2ms
workflow-execution: style recalc duration 26ms
workflow-execution: layout count 4
workflow-execution: style recalc count 16
workflow-execution: task duration 140ms
workflow-execution: script duration 14ms
workflow-execution: TBT 0ms
workflow-execution: heap used 63.9 MB
workflow-execution: DOM nodes 135
workflow-execution: event listeners 82
Raw data
{
  "timestamp": "2026-09-16T12:38:40.089Z",
  "gitSha": "2c7298d3bff88f47c8579677b8418c52f962d406",
  "branch": "jaewon/fe-2331-account-ui-hosted-composables",
  "measurements": [
    {
      "name": "canvas-idle",
      "durationMs": 2035.4889999999841,
      "styleRecalcs": 7,
      "styleRecalcDurationMs": 9.182,
      "layouts": 0,
      "layoutDurationMs": 0,
      "taskDurationMs": 597.8180000000001,
      "heapDeltaBytes": 8288140,
      "heapUsedBytes": 70333692,
      "domNodes": -260,
      "jsHeapTotalBytes": 4972544,
      "scriptDurationMs": 12.252000000000002,
      "eventListeners": -156,
      "totalBlockingTimeMs": 0,
      "frameDurationMs": 16.666666666666668,
      "p95FrameDurationMs": 16.800000000000182
    },
    {
      "name": "canvas-idle",
      "durationMs": 2017.673000000059,
      "styleRecalcs": 7,
      "styleRecalcDurationMs": 7.774,
      "layouts": 0,
      "layoutDurationMs": 0,
      "taskDurationMs": 585.829,
      "heapDeltaBytes": 11547276,
      "heapUsedBytes": 72723648,
      "domNodes": -265,
      "jsHeapTotalBytes": 4448256,
      "scriptDurationMs": 13.058,
      "eventListeners": -154,
      "totalBlockingTimeMs": 0,
      "frameDurationMs": 16.666666666666668,
      "p95FrameDurationMs": 16.699999999999818
    },
    {
      "name": "canvas-mouse-sweep",
      "durationMs": 1928.2019999999989,
      "styleRecalcs": 80,
      "styleRecalcDurationMs": 35.123000000000005,
      "layouts": 14,
      "layoutDurationMs": 4.927,
      "taskDurationMs": 949.5089999999999,
      "heapDeltaBytes": 5596068,
      "heapUsedBytes": 67975840,
      "domNodes": -264,
      "jsHeapTotalBytes": 6021120,
      "scriptDurationMs": 178.088,
      "eventListeners": -184,
      "totalBlockingTimeMs": 0,
      "frameDurationMs": 16.670000000000012,
      "p95FrameDurationMs": 16.700000000000728
    },
    {
      "name": "canvas-mouse-sweep",
      "durationMs": 1949.2910000000165,
      "styleRecalcs": 82,
      "styleRecalcDurationMs": 36.013,
      "layouts": 14,
      "layoutDurationMs": 4.724000000000001,
      "taskDurationMs": 972.8599999999999,
      "heapDeltaBytes": 4072124,
      "heapUsedBytes": 66600236,
      "domNodes": -262,
      "jsHeapTotalBytes": 5234688,
      "scriptDurationMs": 181.974,
      "eventListeners": -154,
      "totalBlockingTimeMs": 0,
      "frameDurationMs": 16.666666666666668,
      "p95FrameDurationMs": 16.699999999999818
    },
    {
      "name": "canvas-zoom-sweep",
      "durationMs": 1735.2779999999939,
      "styleRecalcs": 32,
      "styleRecalcDurationMs": 18.584999999999997,
      "layouts": 6,
      "layoutDurationMs": 1.43,
      "taskDurationMs": 416.859,
      "heapDeltaBytes": 2174016,
      "heapUsedBytes": 64619692,
      "domNodes": 74,
      "jsHeapTotalBytes": 4980736,
      "scriptDurationMs": 16.888,
      "eventListeners": 21,
      "totalBlockingTimeMs": 0,
      "frameDurationMs": 16.666666666666668,
      "p95FrameDurationMs": 16.700000000000728
    },
    {
      "name": "canvas-zoom-sweep",
      "durationMs": 1739.2230000000382,
      "styleRecalcs": 31,
      "styleRecalcDurationMs": 19.123999999999995,
      "layouts": 6,
      "layoutDurationMs": 1.554,
      "taskDurationMs": 424.313,
      "heapDeltaBytes": 1993204,
      "heapUsedBytes": 63647000,
      "domNodes": 76,
      "jsHeapTotalBytes": 4980736,
      "scriptDurationMs": 15.943000000000003,
      "eventListeners": 19,
      "totalBlockingTimeMs": 0,
      "frameDurationMs": 16.670000000000012,
      "p95FrameDurationMs": 16.800000000000182
    },
    {
      "name": "dom-widget-clipping",
      "durationMs": 722.4250000000438,
      "styleRecalcs": 11,
      "styleRecalcDurationMs": 9.541,
      "layouts": 0,
      "layoutDurationMs": 0,
      "taskDurationMs": 484.32,
      "heapDeltaBytes": 17883044,
      "heapUsedBytes": 80354208,
      "domNodes": 18,
      "jsHeapTotalBytes": 5242880,
      "scriptDurationMs": 176.65200000000002,
      "eventListeners": 2,
      "totalBlockingTimeMs": 0,
      "frameDurationMs": 16.666666666666668,
      "p95FrameDurationMs": 16.700000000000728
    },
    {
      "name": "dom-widget-clipping",
      "durationMs": 713.989999999967,
      "styleRecalcs": 11,
      "styleRecalcDurationMs": 9.411999999999999,
      "layouts": 0,
      "layoutDurationMs": 0,
      "taskDurationMs": 489.08299999999997,
      "heapDeltaBytes": 18257084,
      "heapUsedBytes": 80340184,
      "domNodes": 18,
      "jsHeapTotalBytes": 5767168,
      "scriptDurationMs": 174.485,
      "eventListeners": 2,
      "totalBlockingTimeMs": 0,
      "frameDurationMs": 16.666666666666668,
      "p95FrameDurationMs": 16.700000000000728
    },
    {
      "name": "large-graph-idle",
      "durationMs": 2009.8350000000096,
      "styleRecalcs": 4,
      "styleRecalcDurationMs": 5.975999999999999,
      "layouts": 0,
      "layoutDurationMs": 0,
      "taskDurationMs": 691.9399999999999,
      "heapDeltaBytes": 19355440,
      "heapUsedBytes": 83319596,
      "domNodes": -249,
      "jsHeapTotalBytes": 0,
      "scriptDurationMs": 38.864999999999995,
      "eventListeners": -152,
      "totalBlockingTimeMs": 0,
      "frameDurationMs": 16.666666666666668,
      "p95FrameDurationMs": 16.800000000000182
    },
    {
      "name": "large-graph-idle",
      "durationMs": 2053.5429999999906,
      "styleRecalcs": 6,
      "styleRecalcDurationMs": 7.169999999999999,
      "layouts": 0,
      "layoutDurationMs": 0,
      "taskDurationMs": 742.429,
      "heapDeltaBytes": 3617460,
      "heapUsedBytes": 82952384,
      "domNodes": -247,
      "jsHeapTotalBytes": -794624,
      "scriptDurationMs": 40.589,
      "eventListeners": -182,
      "totalBlockingTimeMs": 0,
      "frameDurationMs": 16.666666666666668,
      "p95FrameDurationMs": 16.799999999999272
    },
    {
      "name": "large-graph-pan",
      "durationMs": 2408.0860000000257,
      "styleRecalcs": 65,
      "styleRecalcDurationMs": 11.482000000000003,
      "layouts": 0,
      "layoutDurationMs": 0,
      "taskDurationMs": 1628.6759999999997,
      "heapDeltaBytes": 15181392,
      "heapUsedBytes": 79521844,
      "domNodes": -252,
      "jsHeapTotalBytes": 1536000,
      "scriptDurationMs": 906.343,
      "eventListeners": -152,
      "totalBlockingTimeMs": 0,
      "frameDurationMs": 16.666666666666668,
      "p95FrameDurationMs": 16.700000000000728
    },
    {
      "name": "large-graph-pan",
      "durationMs": 2629.651000000081,
      "styleRecalcs": 67,
      "styleRecalcDurationMs": 12.866,
      "layouts": 0,
      "layoutDurationMs": 0,
      "taskDurationMs": 1817.9669999999999,
      "heapDeltaBytes": -4574388,
      "heapUsedBytes": 75471396,
      "domNodes": -250,
      "jsHeapTotalBytes": 1527808,
      "scriptDurationMs": 900.6909999999999,
      "eventListeners": -182,
      "totalBlockingTimeMs": 0,
      "frameDurationMs": 16.670000000000012,
      "p95FrameDurationMs": 16.800000000000182
    },
    {
      "name": "large-graph-zoom",
      "durationMs": 3866.5079999999534,
      "styleRecalcs": 60,
      "styleRecalcDurationMs": 11.120999999999999,
      "layouts": 60,
      "layoutDurationMs": 14.248000000000001,
      "taskDurationMs": 1865.913,
      "heapDeltaBytes": 8339524,
      "heapUsedBytes": 74670644,
      "domNodes": 0,
      "jsHeapTotalBytes": 0,
      "scriptDurationMs": 848.917,
      "eventListeners": 8,
      "totalBlockingTimeMs": 0,
      "frameDurationMs": 16.66333333333332,
      "p95FrameDurationMs": 16.799999999999272
    },
    {
      "name": "large-graph-zoom",
      "durationMs": 3785.6239999999843,
      "styleRecalcs": 60,
      "styleRecalcDurationMs": 11.156999999999996,
      "layouts": 60,
      "layoutDurationMs": 14.515,
      "taskDurationMs": 1853.708,
      "heapDeltaBytes": 8042720,
      "heapUsedBytes": 74150912,
      "domNodes": 0,
      "jsHeapTotalBytes": 0,
      "scriptDurationMs": 841.93,
      "eventListeners": 10,
      "totalBlockingTimeMs": 0,
      "frameDurationMs": 16.666666666666668,
      "p95FrameDurationMs": 16.700000000000728
    },
    {
      "name": "legacy-node-drag",
      "durationMs": 3116.9229999999857,
      "styleRecalcs": 40,
      "styleRecalcDurationMs": 5.238000000000003,
      "layouts": 0,
      "layoutDurationMs": 0,
      "taskDurationMs": 2083.6740000000004,
      "heapDeltaBytes": 23046596,
      "heapUsedBytes": 89408480,
      "domNodes": 0,
      "jsHeapTotalBytes": 942080,
      "scriptDurationMs": 1061.079,
      "eventListeners": 188,
      "totalBlockingTimeMs": 0,
      "frameDurationMs": 16.666666666666668,
      "p95FrameDurationMs": 16.700000000000728
    },
    {
      "name": "legacy-node-drag",
      "durationMs": 3188.6749999999893,
      "styleRecalcs": 40,
      "styleRecalcDurationMs": 5.274999999999999,
      "layouts": 0,
      "layoutDurationMs": 0,
      "taskDurationMs": 2064.766,
      "heapDeltaBytes": 25069816,
      "heapUsedBytes": 91308240,
      "domNodes": 0,
      "jsHeapTotalBytes": 417792,
      "scriptDurationMs": 1036.144,
      "eventListeners": 188,
      "totalBlockingTimeMs": 0,
      "frameDurationMs": 16.666666666666668,
      "p95FrameDurationMs": 16.80000000000109
    },
    {
      "name": "minimap-idle",
      "durationMs": 2026.674000000014,
      "styleRecalcs": 4,
      "styleRecalcDurationMs": 5.069000000000001,
      "layouts": 0,
      "layoutDurationMs": 0,
      "taskDurationMs": 707.886,
      "heapDeltaBytes": -3105932,
      "heapUsedBytes": 84324572,
      "domNodes": -254,
      "jsHeapTotalBytes": -1019904,
      "scriptDurationMs": 41.671,
      "eventListeners": -152,
      "totalBlockingTimeMs": 0,
      "frameDurationMs": 16.666666666666668,
      "p95FrameDurationMs": 16.800000000000182
    },
    {
      "name": "minimap-idle",
      "durationMs": 2015.677000000096,
      "styleRecalcs": 2,
      "styleRecalcDurationMs": 1.7929999999999995,
      "layouts": 0,
      "layoutDurationMs": 0,
      "taskDurationMs": 665.597,
      "heapDeltaBytes": 19728616,
      "heapUsedBytes": 84721020,
      "domNodes": -255,
      "jsHeapTotalBytes": 0,
      "scriptDurationMs": 39.95,
      "eventListeners": 6,
      "totalBlockingTimeMs": 0,
      "frameDurationMs": 16.66333333333332,
      "p95FrameDurationMs": 16.699999999999818
    },
    {
      "name": "subgraph-dom-widget-clipping",
      "durationMs": 623.0269999999791,
      "styleRecalcs": 46,
      "styleRecalcDurationMs": 10.717999999999998,
      "layouts": 0,
      "layoutDurationMs": 0,
      "taskDurationMs": 438.2180000000001,
      "heapDeltaBytes": 13563996,
      "heapUsedBytes": 77046084,
      "domNodes": 18,
      "jsHeapTotalBytes": 4980736,
      "scriptDurationMs": 150.501,
      "eventListeners": 8,
      "totalBlockingTimeMs": 0,
      "frameDurationMs": 16.666666666666668,
      "p95FrameDurationMs": 16.700000000000728
    },
    {
      "name": "subgraph-dom-widget-clipping",
      "durationMs": 647.4020000000564,
      "styleRecalcs": 46,
      "styleRecalcDurationMs": 12.215,
      "layouts": 0,
      "layoutDurationMs": 0,
      "taskDurationMs": 430.782,
      "heapDeltaBytes": 12698060,
      "heapUsedBytes": 75371304,
      "domNodes": 18,
      "jsHeapTotalBytes": 5505024,
      "scriptDurationMs": 149.49699999999999,
      "eventListeners": 6,
      "totalBlockingTimeMs": 0,
      "frameDurationMs": 16.66333333333335,
      "p95FrameDurationMs": 16.699999999999818
    },
    {
      "name": "subgraph-idle",
      "durationMs": 2018.4580000000096,
      "styleRecalcs": 8,
      "styleRecalcDurationMs": 8.229999999999997,
      "layouts": 0,
      "layoutDurationMs": 0,
      "taskDurationMs": 547.395,
      "heapDeltaBytes": -4917184,
      "heapUsedBytes": 58631476,
      "domNodes": -278,
      "jsHeapTotalBytes": 4972544,
      "scriptDurationMs": 11.434000000000003,
      "eventListeners": -200,
      "totalBlockingTimeMs": 0,
      "frameDurationMs": 16.666666666666668,
      "p95FrameDurationMs": 16.800000000000182
    },
    {
      "name": "subgraph-idle",
      "durationMs": 2023.3839999999645,
      "styleRecalcs": 9,
      "styleRecalcDurationMs": 9.503999999999998,
      "layouts": 0,
      "layoutDurationMs": 0,
      "taskDurationMs": 567.282,
      "heapDeltaBytes": 14586168,
      "heapUsedBytes": 77869424,
      "domNodes": -276,
      "jsHeapTotalBytes": 5234688,
      "scriptDurationMs": 12.203999999999999,
      "eventListeners": -200,
      "totalBlockingTimeMs": 0,
      "frameDurationMs": 16.66333333333332,
      "p95FrameDurationMs": 16.700000000000728
    },
    {
      "name": "subgraph-mouse-sweep",
      "durationMs": 1724.806000000001,
      "styleRecalcs": 77,
      "styleRecalcDurationMs": 31.386999999999997,
      "layouts": 18,
      "layoutDurationMs": 5.891,
      "taskDurationMs": 907.11,
      "heapDeltaBytes": 3356424,
      "heapUsedBytes": 67034916,
      "domNodes": -277,
      "jsHeapTotalBytes": 4972544,
      "scriptDurationMs": 127.31300000000002,
      "eventListeners": -200,
      "totalBlockingTimeMs": 0,
      "frameDurationMs": 16.66333333333335,
      "p95FrameDurationMs": 16.700000000000728
    },
    {
      "name": "subgraph-mouse-sweep",
      "durationMs": 1717.5609999999324,
      "styleRecalcs": 77,
      "styleRecalcDurationMs": 29.143,
      "layouts": 18,
      "layoutDurationMs": 5.543,
      "taskDurationMs": 762.827,
      "heapDeltaBytes": 13197108,
      "heapUsedBytes": 76635924,
      "domNodes": -274,
      "jsHeapTotalBytes": 4710400,
      "scriptDurationMs": 123.45299999999999,
      "eventListeners": -202,
      "totalBlockingTimeMs": 0,
      "frameDurationMs": 16.666666666666668,
      "p95FrameDurationMs": 16.700000000000728
    },
    {
      "name": "subgraph-transition-enter",
      "durationMs": 1434.0369999999893,
      "styleRecalcs": 15,
      "styleRecalcDurationMs": 31.295,
      "layouts": 5,
      "layoutDurationMs": 13.981,
      "taskDurationMs": 1016.413,
      "heapDeltaBytes": 20074072,
      "heapUsedBytes": 103299452,
      "domNodes": 13587,
      "jsHeapTotalBytes": 10485760,
      "scriptDurationMs": 34.67300000000001,
      "eventListeners": 2385,
      "totalBlockingTimeMs": 159,
      "frameDurationMs": 16.666666666666668,
      "p95FrameDurationMs": 16.799999999999272
    },
    {
      "name": "viewport-pan-sweep",
      "durationMs": 9684.986000000037,
      "styleRecalcs": 249,
      "styleRecalcDurationMs": 40.773,
      "layouts": 0,
      "layoutDurationMs": 0,
      "taskDurationMs": 6578.729,
      "heapDeltaBytes": 1304600,
      "heapUsedBytes": 80077484,
      "domNodes": -244,
      "jsHeapTotalBytes": 184320,
      "scriptDurationMs": 3038.249,
      "eventListeners": -134,
      "totalBlockingTimeMs": 0,
      "frameDurationMs": 16.66333333333338,
      "p95FrameDurationMs": 16.700000000000728
    },
    {
      "name": "viewport-pan-sweep",
      "durationMs": 9328.681000000073,
      "styleRecalcs": 248,
      "styleRecalcDurationMs": 42.933,
      "layouts": 0,
      "layoutDurationMs": 0,
      "taskDurationMs": 6383.897,
      "heapDeltaBytes": -4572156,
      "heapUsedBytes": 75475504,
      "domNodes": -250,
      "jsHeapTotalBytes": -77824,
      "scriptDurationMs": 2963.963,
      "eventListeners": -134,
      "totalBlockingTimeMs": 0,
      "frameDurationMs": 16.666666666666668,
      "p95FrameDurationMs": 16.80000000000109
    },
    {
      "name": "vue-large-graph-idle",
      "durationMs": 18401.926000000003,
      "styleRecalcs": 0,
      "styleRecalcDurationMs": 0,
      "layouts": 0,
      "layoutDurationMs": 0,
      "taskDurationMs": 17912.057999999997,
      "heapDeltaBytes": -31003188,
      "heapUsedBytes": 188531500,
      "domNodes": -6542,
      "jsHeapTotalBytes": -430080,
      "scriptDurationMs": 310.32599999999996,
      "eventListeners": -7478,
      "totalBlockingTimeMs": 0,
      "frameDurationMs": 17.780000000000047,
      "p95FrameDurationMs": 16.799999999999272
    },
    {
      "name": "vue-large-graph-idle",
      "durationMs": 17805.33600000001,
      "styleRecalcs": 0,
      "styleRecalcDurationMs": 0,
      "layouts": 0,
      "layoutDurationMs": 0,
      "taskDurationMs": 17354.086000000003,
      "heapDeltaBytes": -21227292,
      "heapUsedBytes": 197464644,
      "domNodes": -6542,
      "jsHeapTotalBytes": 356352,
      "scriptDurationMs": 306.765,
      "eventListeners": -7480,
      "totalBlockingTimeMs": 0,
      "frameDurationMs": 17.780000000000047,
      "p95FrameDurationMs": 16.799999999999272
    },
    {
      "name": "vue-large-graph-pan",
      "durationMs": 22643.167000000005,
      "styleRecalcs": 175,
      "styleRecalcDurationMs": 25.06900000000001,
      "layouts": 0,
      "layoutDurationMs": 0,
      "taskDurationMs": 22451.192,
      "heapDeltaBytes": -30282688,
      "heapUsedBytes": 164241480,
      "domNodes": -6542,
      "jsHeapTotalBytes": -319488,
      "scriptDurationMs": 983.385,
      "eventListeners": -7472,
      "totalBlockingTimeMs": 45,
      "frameDurationMs": 18.333333333333332,
      "p95FrameDurationMs": 16.700000000004366
    },
    {
      "name": "vue-large-graph-pan",
      "durationMs": 21833.69700000003,
      "styleRecalcs": 164,
      "styleRecalcDurationMs": 22.353999999999985,
      "layouts": 0,
      "layoutDurationMs": 0,
      "taskDurationMs": 21657.269,
      "heapDeltaBytes": -41510480,
      "heapUsedBytes": 177518968,
      "domNodes": -6542,
      "jsHeapTotalBytes": -3575808,
      "scriptDurationMs": 986.2059999999999,
      "eventListeners": -7474,
      "totalBlockingTimeMs": 107,
      "frameDurationMs": 17.776666666666763,
      "p95FrameDurationMs": 16.799999999999272
    },
    {
      "name": "vue-node-resize-workload",
      "durationMs": 6443.7230000000345,
      "styleRecalcs": 20,
      "styleRecalcDurationMs": 84.515,
      "layouts": 20,
      "layoutDurationMs": 26.367,
      "taskDurationMs": 6388.893999999999,
      "heapDeltaBytes": -34241296,
      "heapUsedBytes": 160578120,
      "domNodes": -6542,
      "jsHeapTotalBytes": 11214848,
      "scriptDurationMs": 128.62699999999998,
      "eventListeners": -7476,
      "totalBlockingTimeMs": 438,
      "frameDurationMs": 17.776666666666642,
      "p95FrameDurationMs": 16.700000000000728
    },
    {
      "name": "vue-node-resize-workload",
      "durationMs": 4994.373999999993,
      "styleRecalcs": 20,
      "styleRecalcDurationMs": 81.45399999999997,
      "layouts": 20,
      "layoutDurationMs": 25.659000000000002,
      "taskDurationMs": 4958.597999999999,
      "heapDeltaBytes": -4192304,
      "heapUsedBytes": 197388200,
      "domNodes": -6542,
      "jsHeapTotalBytes": 23261184,
      "scriptDurationMs": 102.682,
      "eventListeners": -7478,
      "totalBlockingTimeMs": 144,
      "frameDurationMs": 17.220000000000013,
      "p95FrameDurationMs": 16.80000000000109
    },
    {
      "name": "vue-zoom-out-idle",
      "durationMs": 8913.971000000003,
      "styleRecalcs": 0,
      "styleRecalcDurationMs": 0,
      "layouts": 0,
      "layoutDurationMs": 0,
      "taskDurationMs": 8708.014000000001,
      "heapDeltaBytes": 523484,
      "heapUsedBytes": 174773324,
      "domNodes": 0,
      "jsHeapTotalBytes": 524288,
      "scriptDurationMs": 145.802,
      "eventListeners": -12,
      "totalBlockingTimeMs": 0,
      "frameDurationMs": 17.776666666666642,
      "p95FrameDurationMs": 16.700000000000728
    },
    {
      "name": "vue-zoom-out-idle",
      "durationMs": 8927.915999999983,
      "styleRecalcs": 0,
      "styleRecalcDurationMs": 0,
      "layouts": 0,
      "layoutDurationMs": 0,
      "taskDurationMs": 8634.498000000001,
      "heapDeltaBytes": 6642836,
      "heapUsedBytes": 190575516,
      "domNodes": 0,
      "jsHeapTotalBytes": 1310720,
      "scriptDurationMs": 146.83800000000002,
      "eventListeners": -12,
      "totalBlockingTimeMs": 0,
      "frameDurationMs": 18.330000000000048,
      "p95FrameDurationMs": 16.799999999999272
    },
    {
      "name": "workflow-execution",
      "durationMs": 496.7509999999038,
      "styleRecalcs": 19,
      "styleRecalcDurationMs": 29.605999999999998,
      "layouts": 6,
      "layoutDurationMs": 3.077,
      "taskDurationMs": 166.013,
      "heapDeltaBytes": 5312520,
      "heapUsedBytes": 67272100,
      "domNodes": 151,
      "jsHeapTotalBytes": 262144,
      "scriptDurationMs": 18.272000000000002,
      "eventListeners": 81,
      "totalBlockingTimeMs": 0,
      "frameDurationMs": 16.66333333333332,
      "p95FrameDurationMs": 16.700000000000728
    },
    {
      "name": "workflow-execution",
      "durationMs": 461.2090000000535,
      "styleRecalcs": 13,
      "styleRecalcDurationMs": 22.124,
      "layouts": 2,
      "layoutDurationMs": 0.6479999999999999,
      "taskDurationMs": 114.66399999999999,
      "heapDeltaBytes": 4885676,
      "heapUsedBytes": 66723364,
      "domNodes": 119,
      "jsHeapTotalBytes": 262144,
      "scriptDurationMs": 10.472,
      "eventListeners": 83,
      "totalBlockingTimeMs": 0,
      "frameDurationMs": 16.66333333333335,
      "p95FrameDurationMs": 16.700000000000728
    }
  ]
}

🔬 E2E Coverage

Metric Covered Total Pct
Lines 50945 77294 65.9% 🟡
Functions 0 0 — —
Branches 0 0 — —
Top 10 files by uncovered lines
File Coverage Missed
src/LGraphCanvas.ts 67.6% 1157
src/LGraphNode.ts 69.9% 388
src/extensions/core/cameraInfo/CameraInfoViewport.ts 2.0% 343
src/renderer/extensions/layerEditor/composables/useLayerEditorSession.ts 40.1% 332
src/platform/workspace/stores/workspaceAuthStore.ts 33.1% 331
src/platform/workspace/stores/billingOperationStore.ts 7.9% 313
src/LGraph.ts 79.1% 263
src/platform/workspace/stores/teamWorkspaceStore.ts 38.9% 256
src/scripts/app.ts 71.8% 251
src/core/billing/operationLifecycle.ts 0.9% 226

@github-actions github-actions Bot added the risk:xhigh PR risk grade (advisory shadow check; grader-owned) label Sep 16, 2026
@codecov

codecov Bot commented Sep 16, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 99.00498% with 2 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
...ckages/account-ui/src/billing/usePaymentMethods.ts 90.90% 1 Missing and 1 partial ⚠️
@@                               Coverage Diff                                @@
##           jaewon/fe-2331-plans-payment-methods-readers   #17799      +/-   ##
================================================================================
+ Coverage                                         82.53%   82.55%   +0.01%     
================================================================================
  Files                                              2841     2844       +3     
  Lines                                            141774   141867      +93     
  Branches                                          36201    38053    +1852     
================================================================================
+ Hits                                             117018   117123     +105     
+ Misses                                            23550    23537      -13     
- Partials                                           1206     1207       +1     
Flag Coverage Δ
e2e 65.98% <0.00%> (+0.02%) ⬆️
unit 78.55% <99.00%> (+0.02%) ⬆️
website-unit 74.60% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines Coverage Δ
...ount-ui/src/billing/__fixtures__/billingHarness.ts 94.80% <100.00%> (+1.36%) ⬆️
packages/account-ui/src/billing/billingClient.ts 83.33% <100.00%> (+3.33%) ⬆️
packages/account-ui/src/billing/usePlans.ts 100.00% <100.00%> (ø)
...ages/account-ui/src/billing/usePreviewSubscribe.ts 100.00% <100.00%> (ø)
...s/account/src/core/billing/subscriptionCommands.ts 95.19% <100.00%> (ø)
packages/billing-contract/src/contract.ts 100.00% <100.00%> (ø)
packages/billing-contract/src/entryFields.ts 100.00% <100.00%> (ø)
packages/billing-contract/src/entryParser.ts 100.00% <100.00%> (ø)
packages/billing-contract/src/entryUrl.ts 100.00% <100.00%> (ø)
packages/billing-contract/src/identifiers.ts 100.00% <100.00%> (ø)
... and 6 more

... and 11 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@CodeJuggernaut CodeJuggernaut left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The composables mirror useCredits, quotes are single-flight down to the transport, and both dispose lists carry the new readers. Sequencing: invalidateAndRefresh inherits the invalidate gap noted on #17798 until that lands.

@christian-byrne christian-byrne left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The single-flight quote is correct — I tried to get loading stuck and could not. abandon() clearing it before the next attempt takes over, plus the attempt !== latest fence before any publish, covers the interleavings I could construct, and an aborted request comes back as a coded REQUEST_FAILED rather than a throw, so there is no path that leaves the flag set.

One finding, and it is the #17442 exposure arriving one layer up.

SUPERSEDED is treated as an ordinary failure, and the data it condemns stays on screen

The core goes out of its way to produce a distinct code when the scope moves under a read. paymentMethods.ts even names the hazard:

A list that arrives after the host moved to another workspace names cards the current one cannot charge.

The composables then do this, in all three:

if (result.status === 'ok') {
  methods.value = result.value.methods
  failure.value = undefined
} else {
  failure.value = result        // methods.value untouched
}

with the intent stated in the docstring:

The last read's failure; a failed refresh keeps the previous list on screen.

That is the right call for a network blip or a 5xx — dropping a good catalog because one refresh timed out would be worse. It is the wrong call for SUPERSEDED, which is the one failure that means this data belongs to a scope you are no longer in. SUPERSEDED appears nowhere in packages/account-ui outside billingClient.test.ts fixtures, so nothing distinguishes the two.

Concretely, after a workspace switch: the reader has correctly dropped its snapshot, the next refresh() returns SUPERSEDED, and usePaymentMethods keeps the previous workspace's saved cards rendered. That is the exposure #17442 closed in the core, reopened in the view layer by a copy the core cannot reach.

usePreviewSubscribe is the same shape with less ceremony: preview is a plain ref with no scope awareness at all, cleared only by a manual reset(). A quote priced for workspace A stays on screen in workspace B until someone quotes again.

I do not think the composables should subscribe to scope themselves — that would undo the ownership boundary #17662 drew, where the host builds the core once and the composables only consume. The narrow version is to stop treating one code like the others:

} else if (result.code === 'SUPERSEDED') {
  methods.value = undefined
  failure.value = undefined      // not the user's problem to see
} else {
  failure.value = result
}

Clearing rather than surfacing, because a scope change is not an error the user did anything to cause and there is nothing for them to retry.

If instead the intent is that the host clears these on scope change, then that is an obligation crossing an ownership boundary — the same shape as the disposal finding on #17662 — and it needs saying in the docstrings, which currently say the opposite. Right now a host reading "a failed refresh keeps the previous list on screen" will reasonably conclude this is handled.

Verified

  • No serverCode and no server text in any composable; failures surface as coded BillingFailure.
  • discounts[].code / name are rendered rather than matched, consistent with what #17797 settled.
  • shallowReadonly on every exposed ref, so a consumer cannot write back into state the composable owns.
  • Composables do not dispose the readers, which is correct under #17662's boundary.

CI green.

@dante01yoon

Copy link
Copy Markdown
Collaborator Author

Fixed in 99c6306.

SUPERSEDED is now its own branch in all three composables: the value is cleared and no failure is surfaced, because a scope change is not something the user caused or can retry. Every other code keeps the previous value, which is still right for a blip or a 5xx.

  • usePlans, usePaymentMethods, usePreviewSubscribe: plans / methods / preview set to undefined, failure left undefined.
  • The docstrings said the opposite ("a failed refresh keeps the previous list on screen"), so they now name the exception. A host reading them is no longer told this is handled.

Tests. The harness session can move workspace now, so the two reader-backed cases drive a real scope change through the core instead of a stubbed code:

  • usePlans > drops the catalog without reporting a failure when the host changes workspace
  • usePaymentMethods > drops the cards without reporting a failure when the host changes workspace
  • usePreviewSubscribe > drops the quote without reporting a failure when the scope moves under it — a quote has no reader, so the transport answers SUPERSEDED, which is where a POST learns the scope moved.

All three fail against the unfixed composables with the previous workspace's data still on screen, e.g. the workspace the host moved to cannot charge these cards: expected [ { brand: 'visa', ... }, ...(1) ] to be undefined. 37 pass in packages/account-ui/src/billing; fallow clean on the changed files.

One I did not take: useCredits has the same shape and the same gap, but it is on main and outside this PR's diff, so widening this PR to it looked wrong. Happy to do it as a follow-up if you would rather not leave it.

#17807 and #17809 pick this up on their next rebase.

@christian-byrne christian-byrne left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving. The fix is exactly right, in all three:

} else if (result.code === 'SUPERSEDED') {
  methods.value = undefined
  failure.value = undefined
}

Cleared rather than surfaced, which is the part I cared about — a scope change is not something the user did and there is nothing for them to retry, so showing them an error for it would just be noise attached to data that has already vanished.

One sibling left behind, and it is the original one

The three composables in this PR now distinguish SUPERSEDED. The five that predate it do not — useBillingOperation, useCheckout, useCredits, usePaymentAttempt, useTopUp have zero references to it.

useCredits is the one that matters, because it is the same shape byte for byte:

if (result.status === 'ok') {
  balance.value = result.value.balance
  failure.value = undefined
} else {
  failure.value = result        // balance.value untouched, SUPERSEDED included
}

and its docstring still reads "a failed refresh keeps the previous balance on screen."

That is #17442 exactly. The finding that opened this whole stack was a reader serving the previous account's balance, the core closed it, and the view layer has been holding a copy of it ever since. After a workspace switch, useCredits keeps the previous workspace's balance rendered until something else happens to clear it.

Not this PR's fault — useCredits is not in its diff, and I would not hold the approval for it. But the pattern is now established and proven, and applying it to useCredits is the same three lines. I would do that one next rather than let it wait for whichever PR happens to touch that file, given it is the balance and given it is the original exposure.

Worth noting for the record: this is the third layer this same exposure has moved through — core readers (#17442), the host ownership boundary (#17662), and now the view layer. Each fix was correct where it landed and the obligation relocated one layer up. If it turns up a fourth time it is worth a line in the ADR rather than another review comment.

CI green, 0 failing and 0 pending.

@dante01yoon
dante01yoon force-pushed the jaewon/fe-2331-plans-payment-methods-readers branch from 92af1b3 to b902a9b Compare September 16, 2026 11:44
dante01yoon added a commit that referenced this pull request Sep 16, 2026
…nd payment-method surfaces (#17809)

Linear FE-2331 / FE-2218.

Stacked on #17807 (session); carries a cherry-pick of #17795
(billing-contract).

## Why

`billing.comfy.org` currently serves one static page: a hard-coded
checkout mockup at `/`. Nothing reads the entry URL a product hands it,
and nothing renders over the billing SDK. This PR gives the hosted app
its `/v1` entry routing plus the first two surfaces that project real
SDK state — the subscription catalog with a plan-change quote, and saved
payment methods with the provider portal round trip.

The entry URL is untrusted routing input. `parseBillingEntry` decides
whether it describes a request the contract knows, and a failed parse
renders a coded explanation rather than a redirect, so a misdirected
link stays visible instead of silently landing the customer somewhere
else.

## How

- `router.ts` generates a route per `BILLING_INTENTS` entry —
`subscription` and `pricing` to `SubscriptionView`, `payment-methods` to
`PaymentMethodsView`, `checkout` to the existing `BillingHomeView`
(unchanged), `invoices` and `result` to `ComingSoonView`. `/` keeps the
scaffold checkout page and stays outside the contract.
- A `beforeEach` parses `to.fullPath` and publishes the result into a
tab-local module ref (`useBillingEntry`); `App.vue` renders the
entry-error surface whenever that parse failed, whatever route matched.
No navigation happens on an error.
- The entry is read before the session guard from #17807 runs, so a link
we cannot read explains itself even to a visitor the guard sends to
`/sign-in`: signing in would not repair it. `/` and `/sign-in` carry no
product request and leave the entry alone.
- `HostedSurface.vue` is the shared shell: the dark full-screen layout,
the surface title, the `Return to <product>` link built with
`buildReturnUrl` against the resolved `BILLING_WEB_ENV` (default and
fail-closed value `test`), and the choice between the entry-error
section and the surface itself. Views stay pure projections of
composable state, and a surface only ever renders behind the guard and
the shell, which always provide a client.
- `SubscriptionPanel` reads `usePlans()`, renders each plan as a card
(tier + duration, price, monthly credits, seats), disables an
unavailable plan with its availability reason as our own copy, and on
selection calls `usePreviewSubscribe().quote({ planSlug })` and renders
the quote. Confirm is present and disabled behind the scaffold's
existing `checkout.sdkPending` line.
- `PaymentMethodsPanel` reads `usePaymentMethods()`, marks the default
card, and opens the provider portal through `commands.openPaymentPortal`
with this page's own href plus a `portal=return` marker. On the way back
it invalidates and re-reads once, then strips the marker with
`router.replace`.
- Every server-chosen value reaches the screen as a coded lookup with a
generic fallback: availability reasons, transition types, billing
failure codes, entry error codes, saved payment method types. The card
brand and its last four digits are the one server-supplied pair the UI
interpolates; no other server text is rendered.
- `bigint` money fields convert with `Number()` only at the `n()`/`d()`
formatting boundary.

## AS-IS / TO-BE

AS-IS: a `/v1/subscription` link has no surface of its own — the
catch-all redirects it to `/`, the scaffold's static checkout mockup,
and the product's entry parameters are dropped on the way.

TO-BE: `/v1/subscription` renders the catalog with the current plan
marked and an unavailable plan explained, selecting a plan adds the
server's plan-change quote with an inert confirm, `/v1/payment-methods`
lists saved cards with the default marked beside the provider-portal
button, and a link the contract cannot read gets a coded explanation
instead of a redirect.

| AS-IS | TO-BE |
| --- | --- |
| `/v1/subscription?product=comfyui&return_to=comfyui_workspace`
redirects to the static checkout page<br><img width="420"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/refs/heads/assets/pr-17809-screenshots/asis-v1-subscription.png">
| The same link renders the subscription surface<br><img width="420"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/refs/heads/assets/pr-17809-screenshots/tobe-subscription.png">
|
| TO-BE — plan-change quote after selecting Pro · Monthly<br><img
width="420"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/refs/heads/assets/pr-17809-screenshots/tobe-subscription-quote.png">
| TO-BE — `/v1/payment-methods` with the default card marked<br><img
width="420"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/refs/heads/assets/pr-17809-screenshots/tobe-payment-methods.png">
|
| — | TO-BE — a link the contract cannot read
(`/v1/subscription?product=nope`)<br><img width="420"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/refs/heads/assets/pr-17809-screenshots/tobe-entry-error.png">
|

## Testing

`apps/billing-web` unit tests (`@testing-library/vue`, happy-dom): the
app suite is 85 passing, 44 of them in the four files this PR touches:

- `router.test.ts` — each intent opens its surface, the parsed entry is
published, every entry-error code renders its own copy (including on the
checkout route, proving the error surface wins over the matched route),
an unrecognised path stays where it is, and `/` remains outside the
contract. The guard rows from #17807 join the same file: a signed-out
visitor is sent to `/sign-in` with the surface to come back to, and an
unreadable link keeps its error through that redirect.
- `SubscriptionView.test.ts` — current plan named, catalog priced, an
unavailable plan disabled with its reason, selecting a plan calls
`previewSubscribe` with `{ planSlug }` and renders the formatted quote
with confirm disabled, a refused quote and a failed catalog read both
render coded copy.
- `PaymentMethodsView.test.ts` — cards listed with the default marked,
the portal button navigates to the returned URL, and `portal=return`
triggers exactly one invalidate plus one read before the marker is
stripped.
- `HostedSurface.test.ts` — the arriving intent's content renders,
return link href from `buildReturnUrl`, no link when the entry named no
destination.

Gates: `pnpm typecheck`, `pnpm lint`, `pnpm format`, `pnpm knip`, `pnpm
--filter @comfyorg/billing-web build`, `fallow audit` all pass.

## Not in this PR

- Subscribing through the SDK — the confirm button is deliberately
inert.
- Invoices, which wait on the backend.
- Putting `apps/billing-web` unit tests in the CI loop:
`ci-tests-unit.yaml` runs `packages/*` only, so this suite runs locally
but not on a PR. Follow-up.
## Where this sits in the plan

Billing SDK track FE-2210 ([implementation plan
V2](https://app.notion.com/p/3d86d73d36508152b92cdbdfdfe83ac8)). Hybrid
model: top-up in-app, subscription management / invoices / payment
methods on the hosted billing app.

| Phase | Item | Ticket | Status |
| --- | --- | --- | --- |
| 1-2 | Session core, transport, readers | FE-2211/2212/2213 | merged |
| 3 | Operation lifecycle, commands, eight-state projection |
FE-2227/2214/2223 | merged (#17655) |
| 4 | `@comfyorg/account-ui` composables + `CheckoutSteps` | FE-2215 |
merged (#17662, #17663) |
| 5 slice 1 | Top-up through the SDK behind `billing_sdk_topup_enabled`
| FE-2216 | merged (#17665) |
| rollout C | `hosted_billing_destination` server flag read by the host
| FE-2218 | merged (#17716) |
| rollout C | `hostedDestination` port on the lifecycle, value on
operation state | FE-2210/2218 | open (#17783) |
| 7 prep | Scope-source port + credentialed transport (BFF / cookie
hosts) | FE-2218 | open (#17782) |
| 7 prep | `@comfyorg/account` → `@comfyorg/account-core` rename |
FE-2218 | local, opens after #17782 and #17783 |
| 7 prep | `billing-contract` route builder + `return_to` registry |
FE-2218 | open (#17795) |
| 3A-3 | Workshop adapter over `createHostedTopupCheckout` | FE-2214 |
open (#17793) |
| 8 core | `previewSubscribe` command | FE-2331 | open (#17797) |
| 8 core | Plans + saved payment-methods readers | FE-2331 | open
(#17798) |
| 8 ui | account-ui composables (`usePlans`, `usePaymentMethods`,
`usePreviewSubscribe`) | FE-2331 | open (#17799) |
| 7 | billing-web own-origin session, sign-in, SDK composition | FE-2218
| open (#17807) |
| 8 ui | billing-web `/v1` entry routing + subscription / payment-method
surfaces | FE-2331 | **this PR** |
| 7 | npm publish (`ingest-types`, `account-core`, `billing-contract`),
Platform install, billing-web live top-up | FE-2218 | todo |
| 6 | Contract tests + live E2E per flow × consumer | FE-2217 | todo |
| 5 slice 2 | Subscription flows through the SDK | FE-2216 | todo
(plan-change decision) |
| follow-up | One `needsCustomerAttention` predicate (from the #17665
review) | FE-2216 | open (#17792) |
| follow-up | Opaque `BillingServerCode` (from the #17656 review) |
FE-2227 | open (#17794) |

```mermaid
flowchart LR
  P3["Phase 3 core lifecycle (merged)"]
  P4["Phase 4 account-ui (merged)"]
  P5["Phase 5 slice 1 top-up flag (merged)"]
  FC["PR 17716 hosted_billing_destination flag (merged)"]
  HD["PR 17783 hostedDestination port"]
  SS["PR 17782 scope-source port + credentialed transport"]
  RN["account-core rename"]
  RB["billing-contract route builder + return_to"]
  WS["Workshop adapter"]
  P8PV["previewSubscribe command"]
  P8RD["plans + payment-methods readers"]
  P8["account-ui hosted composables"]
  BWS["billing-web session + sign-in"]
  BWV["billing-web /v1 surfaces"]
  PUB["npm publish account-core / billing-contract"]
  P7["Phase 7 host proof: Platform + billing-web live"]
  P6["Phase 6 evidence"]
  S2["Phase 5 slice 2 subscription"]
  FU9["customer-attention predicate"]
  FU11["opaque BillingServerCode"]
  P3 --> HD
  FC --> HD
  HD --> RB
  P3 --> SS
  SS --> P7
  RB --> P7
  P3 --> RN
  RN --> PUB
  RB --> PUB
  PUB --> P7
  P3 --> P8PV
  P3 --> P8RD
  P8PV --> P8
  P8RD --> P8
  P4 --> P8
  P8 --> S2
  P8 --> BWS
  BWS --> BWV
  RB --> BWV
  BWV --> P7
  P5 --> P6
  P5 --> WS
  P5 --> FU9
  P3 --> FU11
  style P3 fill:#d4edda,stroke:#155724
  style P4 fill:#d4edda,stroke:#155724
  style P5 fill:#d4edda,stroke:#155724
  style FC fill:#d4edda,stroke:#155724
  style BWV stroke:#0366d6,stroke-width:4px
```
@dante01yoon

Copy link
Copy Markdown
Collaborator Author

Heads-up: this PR is now CONFLICTING / DIRTY against its base. Not touched, because a restack needs a force-push and that would drop the approval from 16 minutes ago — flagging rather than doing it.

What happened: jaewon/fe-2331-plans-payment-methods-readers (#17798) was rebased onto the scopeSource migration at 07:50Z, so this branch still carries the pre-rebase copy of the readers. git merge-tree b902a9b7e4 99c6306967 reports six conflicts:

  • packages/account/src/core/billing/plans.ts (add/add)
  • packages/account/src/core/billing/paymentMethods.ts (add/add)
  • packages/account/src/core/billing/plans.test.ts (add/add)
  • packages/account/src/core/billing/paymentMethods.test.ts (add/add)
  • packages/account-ui/src/billing/__fixtures__/billingHarness.ts (content)
  • src/platform/workspace/billing/sdk/createBillingSdk.ts (content)

The four add/add ones are purely the old session copies meeting the new scopeSource ones; they disappear once the old base commit is dropped.

Restack when you pick it up:

git rebase --onto b902a9b7e4 c59f59d8a2 jaewon/fe-2331-account-ui-hosted-composables

Two commits below this PR's own work want dropping: c59f59d8a2 (superseded by 441eccd5c8 + a3fb00f1c6 + b902a9b7e4 on the new base) and ab1b86234e, the #17797 cherry-pick that landed on main as squash 9279845759 — that one is not patch-identical to the squash, so it will not drop on its own and needs to be skipped by hand.

Nothing else on the stack is affected yet: #17807 still measures clean against this branch and will inherit the same break the moment this one moves.

@dante01yoon dante01yoon removed needs-backport Fix/change that needs to be cherry-picked to the current feature freeze branch core/1.54 Backport PRs for core 1.54 cloud/1.54 Backport PRs for cloud 1.54 labels Sep 16, 2026
SUPERSEDED is the one failure that means the data belongs to a scope the
host has left, and the composables were treating it as an ordinary one:
the failed refresh kept the previous workspace's saved cards, plan catalog
and quote on screen, reopening in the view layer what the core closed.

usePlans, usePaymentMethods and usePreviewSubscribe now clear their value
on SUPERSEDED and surface no failure — a scope change is not something the
user caused or can retry. Every other code keeps the previous value, which
is still right for a blip or a 5xx.

The docstrings said the opposite, so they say the exception now. The test
harness session can move workspace, so the two reader-backed cases drive a
real scope change through the core rather than a stubbed code.
@dante01yoon

Copy link
Copy Markdown
Collaborator Author

Took the useCredits point as its own PR: #17824 (clears balance and failure on SUPERSEDED, docstring corrected, one table row through the real reader with a movable fake session). The other four pre-existing composables were checked one by one and left alone: useBillingOperation republishes the lifecycle's own superseded state, usePaymentAttempt's projection already maps superseded back to select, and useCheckout / useTopUp expose command results that carry no scope-bound data. Rationale per composable is in that PR's body.

pull Bot pushed a commit to Penguinjanator/ComfyUI_frontend that referenced this pull request Sep 16, 2026
…e change as superseded (Comfy-Org#17828)

Linear FE-2331. Follow-up from the Comfy-Org#17798 review.

## Why

A billing read that fails is still an answer about the scope it was
issued for. When the host switches workspace or disposes the reader
while the request is in flight, the credits, status, and capabilities
readers hand the caller back the original failure code —
`REQUEST_FAILED`, `NOT_FOUND`, `CONFLICT` — instead of `SUPERSEDED`. A
caller that distinguishes "this read no longer applies" from "this read
failed" then retries, reports, or surfaces an error banner for a
workspace the user already left.

The same gap was fixed for `plans.ts` and `paymentMethods.ts` in Comfy-Org#17798;
these three readers were written before that and kept the old shape.

## Root cause

The lifecycle fence ran only on the success path:

```ts
const result = await requestBalance(scope)
if (result.status !== 'ok') {
  if (result.code === 'ACCESS_DENIED' && scopeTracker.isCurrent(context)) {
    snapshot = undefined
  }
  return result            // <- returns before the fence
}

if (lifetime.disposed || !scopeTracker.isCurrent(context)) {
  return { status: 'error', code: 'SUPERSEDED' }
}
```

Because the failure branch returned early, the failure never reached the
fence. The `ACCESS_DENIED` snapshot drop compensated with its own
`isCurrent` check, which is why the stale-scope case was handled for the
cache but not for the returned result.

## How

Move the fence to run immediately after the request settles, before
`result.status` is inspected, in `credits.ts`, `status.ts`, and
`capabilities.ts`. Any result — ok or error — that lands after a dispose
or a scope change is now reported as `SUPERSEDED`. The denial drop keeps
working for the current scope, and its now-redundant `isCurrent` guard
is removed since the fence has already returned for a stale one.

`capabilities.ts` is included because it carried the identical gap;
`plans.ts` and `paymentMethods.ts` already have this shape from Comfy-Org#17798.

## AS-IS / TO-BE

No UI change. This is SDK-internal error-code behavior on
`packages/account`:

| | AS-IS | TO-BE |
| --- | --- | --- |
| 500 lands after a workspace change | `{ code: 'REQUEST_FAILED',
httpStatus: 500 }` | `{ code: 'SUPERSEDED' }` |
| 500 lands after `dispose()` | `{ code: 'REQUEST_FAILED', httpStatus:
500 }` | `{ code: 'SUPERSEDED' }` |
| 500 lands in the current scope | `{ code: 'REQUEST_FAILED',
httpStatus: 500 }` | unchanged |
| 403 lands in the current scope | drops the snapshot | unchanged |

## Testing

- Added an `it.for` over two rows — the workspace changes, the reader is
disposed — to each of `credits.test.ts`, `status.test.ts`, and
`capabilities.test.ts`, gating a 500 behind the existing release-gate
transport helper so the failure settles after the supersede.
- All six new rows fail against the pre-fix source (`expected { status:
'error', code: 'REQUEST_FAILED', httpStatus: 500 } to deeply equal {
status: 'error', code: 'SUPERSEDED' }`) and pass with the fence moved.
- `packages/account` suite: 39 files, 634 tests passing.
- `pnpm typecheck`, `pnpm lint`, `pnpm format:check`, `pnpm knip`, and
`fallow audit --changed-since origin/main` all clean.
## Where this sits in the plan

Billing SDK track FE-2210 ([implementation plan
V2](https://app.notion.com/p/3d86d73d36508152b92cdbdfdfe83ac8)). Hybrid
model: top-up in-app, subscription management / invoices / payment
methods on the hosted billing app.

| Phase | Item | Ticket | Status |
| --- | --- | --- | --- |
| 1-2 | Session core, transport, readers | FE-2211/2212/2213 | merged |
| 3 | Operation lifecycle, commands, eight-state projection |
FE-2227/2214/2223 | merged (Comfy-Org#17655) |
| 4 | `@comfyorg/account-ui` composables + `CheckoutSteps` | FE-2215 |
merged (Comfy-Org#17662, Comfy-Org#17663) |
| 5 slice 1 | Top-up through the SDK behind `billing_sdk_topup_enabled`
| FE-2216 | merged (Comfy-Org#17665) |
| rollout C | `hosted_billing_destination` server flag read by the host
| FE-2218 | merged (Comfy-Org#17716) |
| rollout C | `hostedDestination` port on the lifecycle, value on
operation state | FE-2210/2218 | open (Comfy-Org#17783) |
| 7 prep | Scope-source port + credentialed transport (BFF / cookie
hosts) | FE-2218 | merged (Comfy-Org#17782) |
| 7 prep | `@comfyorg/account` → `@comfyorg/account-core` rename |
FE-2218 | local, opens after Comfy-Org#17783 and Comfy-Org#17794 |
| 7 prep | `billing-contract` route builder + `return_to` registry |
FE-2218 | merged (Comfy-Org#17795) |
| 3A-3 | Workshop adapter over `createHostedTopupCheckout` | FE-2214 |
merged (Comfy-Org#17793) |
| 8 core | `previewSubscribe` command | FE-2331 | merged (Comfy-Org#17797) |
| 8 core | Plans + saved payment-methods readers | FE-2331 | open
(Comfy-Org#17798, whole Phase 8) |
| 8 ui | account-ui composables (`usePlans`, `usePaymentMethods`,
`usePreviewSubscribe`) | FE-2331 | in Comfy-Org#17798 |
| 7 | billing-web own-origin session, sign-in, SDK composition | FE-2218
| in Comfy-Org#17798 |
| 7 | billing-web unit tests in CI (`ci-billing-web-unit.yaml`) |
FE-2218 | open (Comfy-Org#17827) |
| 7 | ingest CORS + top-up return hosts for billing.comfy.org and its
previews (Comfy-Org/cloud) | FE-2218 | open (cloud PR 9512) |
| 8 ui | billing-web `/v1` entry routing + subscription / payment-method
surfaces | FE-2331 | in Comfy-Org#17798 |
| 7 | npm publish (`ingest-types`, `account-core`, `billing-contract`),
Platform install, billing-web live top-up | FE-2218 | todo |
| 6 | Contract tests + live E2E per flow × consumer | FE-2217 | todo |
| 5 slice 2 | Subscription flows through the SDK | FE-2216 | todo
(plan-change decision) |
| follow-up | One `needsCustomerAttention` predicate (from the Comfy-Org#17665
review) | FE-2216 | merged (Comfy-Org#17792) |
| follow-up | Opaque `BillingServerCode` (from the Comfy-Org#17656 review) |
FE-2227 | open (Comfy-Org#17794) |
| follow-up | `useCredits` clears on `SUPERSEDED` (from the Comfy-Org#17799
review) | FE-2215 | open (Comfy-Org#17824) |
| follow-up | credits / status / capabilities readers fence a late
failure as `SUPERSEDED` (from the Comfy-Org#17798 review) | FE-2331 | **this PR**
|

```mermaid
flowchart LR
  P3["Phase 3 core lifecycle (merged)"]
  P4["Phase 4 account-ui (merged)"]
  P5["Phase 5 slice 1 top-up flag (merged)"]
  FC["PR 17716 hosted_billing_destination flag (merged)"]
  HD["PR 17783 hostedDestination port"]
  SS["PR 17782 scope-source port + credentialed transport"]
  RN["account-core rename"]
  RB["billing-contract route builder + return_to"]
  WS["Workshop adapter"]
  P8PV["previewSubscribe command"]
  P8RD["plans + payment-methods readers"]
  P8["account-ui hosted composables"]
  BWS["billing-web session + sign-in"]
  BWV["billing-web /v1 surfaces"]
  CORS["cloud PR 9512 ingest CORS + return hosts"]
  PUB["npm publish account-core / billing-contract"]
  P7["Phase 7 host proof: Platform + billing-web live"]
  P6["Phase 6 evidence"]
  S2["Phase 5 slice 2 subscription"]
  FU9["customer-attention predicate"]
  FU11["opaque BillingServerCode"]
  FU12["useCredits clears on SUPERSEDED"]
  FU13["reader late-failure fence"]
  P3 --> HD
  FC --> HD
  HD --> RB
  P3 --> SS
  SS --> P7
  RB --> P7
  P3 --> RN
  RN --> PUB
  RB --> PUB
  PUB --> P7
  P3 --> P8PV
  P3 --> P8RD
  P8PV --> P8
  P8RD --> P8
  P4 --> P8
  P8 --> S2
  P8 --> BWS
  BWS --> BWV
  RB --> BWV
  BWV --> P7
  CORS --> P7
  P5 --> P6
  P5 --> WS
  P5 --> FU9
  P3 --> FU11
  P4 --> FU12
  P3 --> FU13
  style P3 fill:#d4edda,stroke:#155724
  style P4 fill:#d4edda,stroke:#155724
  style P5 fill:#d4edda,stroke:#155724
  style FC fill:#d4edda,stroke:#155724
  style SS fill:#d4edda,stroke:#155724
  style RB fill:#d4edda,stroke:#155724
  style WS fill:#d4edda,stroke:#155724
  style FU9 fill:#d4edda,stroke:#155724
  style P8PV fill:#d4edda,stroke:#155724
  style FU13 stroke:#0366d6,stroke-width:4px
```
pull Bot pushed a commit to Mu-L/ComfyUI_frontend that referenced this pull request Sep 16, 2026
…g the previous scope's (Comfy-Org#17824)

Linear FE-2215. Follow-up from the Comfy-Org#17799 review.

## Why

The exposure this SDK track started from was a reader serving the
previous
account's balance. The core closed it: a read that settles after the
host
moved to another workspace is refused with `SUPERSEDED` rather than
published.
`useCredits` then reopened it in the view layer — it treated that
refusal as an
ordinary failure, kept `balance` untouched, and went on rendering the
credits
of the workspace the user had just left.

## Root cause

`useCredits.refresh` had two branches: publish on `ok`, keep the
previous
balance and surface the failure on anything else. A scope change is
neither. It
is not something the user did, there is nothing to retry, and the value
being
kept belongs to an account that is no longer on screen. The three
composables
added in Comfy-Org#17799 already split that branch out; the five older ones never
mentioned `SUPERSEDED`.

## How

`useCredits` clears both `balance` and `failure` on a `SUPERSEDED` read,
the
same three lines as `usePaymentMethods`, and its docstring keeps the "a
failed
refresh keeps the previous balance" promise only for ordinary failures.

The other four pre-existing composables are unchanged:

- `useBillingOperation` — the lifecycle dispatches `superseded` to every
operation on a scope change and republishes it, so the state this
composable
  holds is already the truthful new one rather than a stale one.
- `usePaymentAttempt` — its visible surface is `projection`, and
  `projectPaymentStep` maps a superseded operation back to `select`.
- `useCheckout` / `useTopUp` — `result` is the outcome handed back to
the
caller of a command, carries no scope-bound data, and the step the
shipped
  `CheckoutSteps` renders comes from the projection above.

The test fixture's fake session can now move to another workspace, so
the real
credits reader produces `SUPERSEDED` the way the workspace switcher
does.

## AS-IS / TO-BE

No UI change. AS-IS: after a workspace switch, a host bound to
`useCredits`
keeps showing the previous workspace's balance until something else
clears it.
TO-BE: the balance goes undefined and the host renders its empty state
until
the read for the new workspace settles, with no error shown for a switch
the
user did not make.

## Testing

`useCredits.test.ts` gains a row that moves the harness to another
workspace
mid-refresh and asserts the balance is dropped with no failure reported;
it
fails on pre-fix code. The existing row proving that an ordinary failed
refresh
keeps the previous balance stays.
## Where this sits in the plan

Billing SDK track FE-2210 ([implementation plan
V2](https://app.notion.com/p/3d86d73d36508152b92cdbdfdfe83ac8)). Hybrid
model: top-up in-app, subscription management / invoices / payment
methods on the hosted billing app.

| Phase | Item | Ticket | Status |
| --- | --- | --- | --- |
| 1-2 | Session core, transport, readers | FE-2211/2212/2213 | merged |
| 3 | Operation lifecycle, commands, eight-state projection |
FE-2227/2214/2223 | merged (Comfy-Org#17655) |
| 4 | `@comfyorg/account-ui` composables + `CheckoutSteps` | FE-2215 |
merged (Comfy-Org#17662, Comfy-Org#17663) |
| 5 slice 1 | Top-up through the SDK behind `billing_sdk_topup_enabled`
| FE-2216 | merged (Comfy-Org#17665) |
| rollout C | `hosted_billing_destination` server flag read by the host
| FE-2218 | merged (Comfy-Org#17716) |
| rollout C | `hostedDestination` port on the lifecycle, value on
operation state | FE-2210/2218 | open (Comfy-Org#17783) |
| 7 prep | Scope-source port + credentialed transport (BFF / cookie
hosts) | FE-2218 | merged (Comfy-Org#17782) |
| 7 prep | `@comfyorg/account` → `@comfyorg/account-core` rename |
FE-2218 | local, opens after Comfy-Org#17783 and Comfy-Org#17794 |
| 7 prep | `billing-contract` route builder + `return_to` registry |
FE-2218 | merged (Comfy-Org#17795) |
| 3A-3 | Workshop adapter over `createHostedTopupCheckout` | FE-2214 |
merged (Comfy-Org#17793) |
| 8 core | `previewSubscribe` command | FE-2331 | merged (Comfy-Org#17797) |
| 8 core | Plans + saved payment-methods readers | FE-2331 | open
(Comfy-Org#17798) |
| 8 ui | account-ui composables (`usePlans`, `usePaymentMethods`,
`usePreviewSubscribe`) | FE-2331 | open (Comfy-Org#17799) |
| 7 | billing-web own-origin session, sign-in, SDK composition | FE-2218
| open (Comfy-Org#17807) |
| 8 ui | billing-web `/v1` entry routing + subscription / payment-method
surfaces | FE-2331 | open (Comfy-Org#17809) |
| 7 | npm publish (`ingest-types`, `account-core`, `billing-contract`),
Platform install, billing-web live top-up | FE-2218 | todo |
| 6 | Contract tests + live E2E per flow × consumer | FE-2217 | todo |
| 5 slice 2 | Subscription flows through the SDK | FE-2216 | todo
(plan-change decision) |
| follow-up | One `needsCustomerAttention` predicate (from the Comfy-Org#17665
review) | FE-2216 | merged (Comfy-Org#17792) |
| follow-up | Opaque `BillingServerCode` (from the Comfy-Org#17656 review) |
FE-2227 | open (Comfy-Org#17794) |
| follow-up | `useCredits` clears on `SUPERSEDED` (from the Comfy-Org#17799
review) | FE-2215 | **this PR** |

```mermaid
flowchart LR
  P3["Phase 3 core lifecycle (merged)"]
  P4["Phase 4 account-ui (merged)"]
  P5["Phase 5 slice 1 top-up flag (merged)"]
  FC["PR 17716 hosted_billing_destination flag (merged)"]
  HD["PR 17783 hostedDestination port"]
  SS["PR 17782 scope-source port + credentialed transport"]
  RN["account-core rename"]
  RB["billing-contract route builder + return_to"]
  WS["Workshop adapter"]
  P8PV["previewSubscribe command"]
  P8RD["plans + payment-methods readers"]
  P8["account-ui hosted composables"]
  BWS["billing-web session + sign-in"]
  BWV["billing-web /v1 surfaces"]
  PUB["npm publish account-core / billing-contract"]
  P7["Phase 7 host proof: Platform + billing-web live"]
  P6["Phase 6 evidence"]
  S2["Phase 5 slice 2 subscription"]
  FU9["customer-attention predicate"]
  FU11["opaque BillingServerCode"]
  FU12["useCredits clears on SUPERSEDED"]
  P3 --> HD
  FC --> HD
  HD --> RB
  P3 --> SS
  SS --> P7
  RB --> P7
  P3 --> RN
  RN --> PUB
  RB --> PUB
  PUB --> P7
  P3 --> P8PV
  P3 --> P8RD
  P8PV --> P8
  P8RD --> P8
  P4 --> P8
  P8 --> S2
  P8 --> BWS
  BWS --> BWV
  RB --> BWV
  BWV --> P7
  P5 --> P6
  P5 --> WS
  P5 --> FU9
  P3 --> FU11
  P4 --> FU12
  style P3 fill:#d4edda,stroke:#155724
  style P4 fill:#d4edda,stroke:#155724
  style P5 fill:#d4edda,stroke:#155724
  style FC fill:#d4edda,stroke:#155724
  style FU12 stroke:#0366d6,stroke-width:4px
```
pull Bot pushed a commit to Mu-L/ComfyUI_frontend that referenced this pull request Sep 16, 2026
…g#17827)

Linear FE-2218.

## Why

`apps/billing-web` has a Vitest suite (`App.test.ts`,
`EmbeddedCheckout.test.ts`, with ~10 more files landing in Comfy-Org#17798) that
runs in zero CI steps today.

`ci-tests-unit.yaml` runs the root Vitest suite and then loops over a
fixed package list (`account account-ui billing-contract
object-info-parser shared-frontend-utils design-system`) —
`@comfyorg/billing-web` is not in that loop, and the workflow's
`changes-filter` `should-run` gate excludes `apps/**` outright, so a
billing-web-only PR skips the job entirely. `apps/website` has its own
`ci-website-unit.yaml`; billing-web had no equivalent. A broken
billing-web test could merge green.

## How

New `.github/workflows/ci-billing-web-unit.yaml`, modelled on
`ci-website-unit.yaml`:

- Triggers on `push` to `main`, `pull_request` (`branches-ignore:
[wip/*, draft/*, temp/*]`), and `merge_group`. No `paths:` filter on the
triggers: a `paths:`-filtered workflow produces no check run at all when
the paths do not match, so it can never be a required check, and it
would leave the merge queue waiting.
- Gating moves into the job graph instead. A `changes` job runs
`./.github/actions/changes-filter`, and `billing-web-unit` is `needs:
changes` with `if: app-billing-web-changes == 'true' || packages-changes
== 'true'`. A new `app-billing-web-changes` output computed from
`apps/billing-web/**` is added to that action, next to the existing
`app-website-changes`; shared deps (`.nvmrc`, root `package.json`,
`pnpm-lock.yaml`, `pnpm-workspace.yaml`) fold in automatically like
every other `app-*` output, and the existing `packages-changes` already
covers `packages/**` — including `account`, `account-ui`, and
`billing-contract`.
- A `billing-web-unit-gate` job (`needs: [changes, billing-web-unit]`,
`if: always()`) emits the stable branch-protection context: it passes
when the unit job succeeded, or when it was skipped *and* filtering
itself succeeded and found no billing-web or package changes, and fails
otherwise. Same success/skip logic as `website-unit-gate`, so a
filter-step failure cannot be mistaken for "nothing to run".
- Standard `ubuntu-latest` + `./.github/actions/setup-frontend` (pnpm,
`.nvmrc` Node, lockfile-keyed pnpm store cache), plus the repo's usual
`${{ github.workflow }}-${{ github.ref }}` cancel-in-progress
concurrency and `contents: read`.
- Runs `pnpm --filter @comfyorg/billing-web test:coverage` and uploads
`apps/billing-web/coverage/lcov.info` to Codecov under flag
`billing-web`, re-rooted with `network_prefix: apps/billing-web/` so
paths cannot collide with root-app coverage. `fail_ci_if_error: ${{
github.event.pull_request.head.repo.fork != true }}`, matching the
website workflow — forks have no token, so upload failures cannot block
outside contributors.
- `codecov.yml` declares the new flag with `paths:
apps/billing-web/src/**` and `carryforward: false`, matching the
`website-unit` entry, so patch coverage is attributed correctly and a
missing upload is not papered over with stale data.

No typecheck or build job here: `pnpm typecheck` (root) already fans out
to `typecheck:billing-web`, `pnpm lint` already runs `pnpm --filter
@comfyorg/billing-web lint`, and both run on every PR through the
ungated `ci-lint-format.yaml`. `vite build` for billing-web is still
uncovered by CI — out of scope for this PR.

## AS-IS / TO-BE

No UI change.

- AS-IS: `grep -rn "billing-web" .github/workflows/` returns nothing.
The billing-web suite executes in no CI job on any event.
- TO-BE: `CI: Billing Web Unit` reports on every PR and merge-queue
candidate. A PR touching `apps/billing-web/**` or `packages/**` executes
the suite with coverage and reports it to Codecov under the
`billing-web` flag; any other PR skips the test job but still emits a
passing `billing-web-unit-gate`, so the check can be marked required.

## Testing

- `pnpm --filter @comfyorg/billing-web test:coverage` — 2 test files, 7
tests passed; 98.33% statements, 100% branches, 90% functions, 98.27%
lines. `apps/billing-web/coverage/lcov.info` written at the path the
workflow uploads.
- `yamllint --config-file .yamllint
.github/workflows/ci-billing-web-unit.yaml
.github/actions/changes-filter/action.yaml codecov.yml` — clean (same
linter and config as `ci-yaml-validation.yaml`). Workflow also parses
and resolves to the expected `on` (`push`/`pull_request`/`merge_group`)
and `jobs` (`changes`, `billing-web-unit`, `billing-web-unit-gate`)
structure.
- `diff` against `ci-website-unit.yaml` shows only name, path, and
filter-output renames plus the narrower `push: branches: [main]` — the
gate job's logic is byte-identical apart from those substitutions.
- Action pinning matches `.pinact.yaml`: `actions/checkout@v7` is in
`ignore_actions`, `codecov/codecov-action` is SHA-pinned to the same
commit `ci-website-unit.yaml` uses.
## Where this sits in the plan

Billing SDK track FE-2210 ([implementation plan
V2](https://app.notion.com/p/3d86d73d36508152b92cdbdfdfe83ac8)). Hybrid
model: top-up in-app, subscription management / invoices / payment
methods on the hosted billing app.

| Phase | Item | Ticket | Status |
| --- | --- | --- | --- |
| 1-2 | Session core, transport, readers | FE-2211/2212/2213 | merged |
| 3 | Operation lifecycle, commands, eight-state projection |
FE-2227/2214/2223 | merged (Comfy-Org#17655) |
| 4 | `@comfyorg/account-ui` composables + `CheckoutSteps` | FE-2215 |
merged (Comfy-Org#17662, Comfy-Org#17663) |
| 5 slice 1 | Top-up through the SDK behind `billing_sdk_topup_enabled`
| FE-2216 | merged (Comfy-Org#17665) |
| rollout C | `hosted_billing_destination` server flag read by the host
| FE-2218 | merged (Comfy-Org#17716) |
| rollout C | `hostedDestination` port on the lifecycle, value on
operation state | FE-2210/2218 | open (Comfy-Org#17783) |
| 7 prep | Scope-source port + credentialed transport (BFF / cookie
hosts) | FE-2218 | merged (Comfy-Org#17782) |
| 7 prep | `@comfyorg/account` → `@comfyorg/account-core` rename |
FE-2218 | local, opens after Comfy-Org#17783 and Comfy-Org#17794 |
| 7 prep | `billing-contract` route builder + `return_to` registry |
FE-2218 | merged (Comfy-Org#17795) |
| 3A-3 | Workshop adapter over `createHostedTopupCheckout` | FE-2214 |
merged (Comfy-Org#17793) |
| 8 core | `previewSubscribe` command | FE-2331 | merged (Comfy-Org#17797) |
| 8 core | Plans + saved payment-methods readers | FE-2331 | open
(Comfy-Org#17798, whole Phase 8) |
| 8 ui | account-ui composables (`usePlans`, `usePaymentMethods`,
`usePreviewSubscribe`) | FE-2331 | in Comfy-Org#17798 |
| 7 | billing-web own-origin session, sign-in, SDK composition | FE-2218
| in Comfy-Org#17798 |
| 7 | billing-web unit tests in CI (`ci-billing-web-unit.yaml`) |
FE-2218 | **this PR** |
| 7 | ingest CORS + top-up return hosts for billing.comfy.org and its
previews (Comfy-Org/cloud) | FE-2218 | open (cloud PR 9512) |
| 8 ui | billing-web `/v1` entry routing + subscription / payment-method
surfaces | FE-2331 | in Comfy-Org#17798 |
| 7 | npm publish (`ingest-types`, `account-core`, `billing-contract`),
Platform install, billing-web live top-up | FE-2218 | todo |
| 6 | Contract tests + live E2E per flow × consumer | FE-2217 | todo |
| 5 slice 2 | Subscription flows through the SDK | FE-2216 | todo
(plan-change decision) |
| follow-up | One `needsCustomerAttention` predicate (from the Comfy-Org#17665
review) | FE-2216 | merged (Comfy-Org#17792) |
| follow-up | Opaque `BillingServerCode` (from the Comfy-Org#17656 review) |
FE-2227 | open (Comfy-Org#17794) |
| follow-up | `useCredits` clears on `SUPERSEDED` (from the Comfy-Org#17799
review) | FE-2215 | open (Comfy-Org#17824) |

```mermaid
flowchart LR
  P3["Phase 3 core lifecycle (merged)"]
  P4["Phase 4 account-ui (merged)"]
  P5["Phase 5 slice 1 top-up flag (merged)"]
  FC["PR 17716 hosted_billing_destination flag (merged)"]
  HD["PR 17783 hostedDestination port"]
  SS["PR 17782 scope-source port + credentialed transport"]
  RN["account-core rename"]
  RB["billing-contract route builder + return_to"]
  WS["Workshop adapter"]
  P8PV["previewSubscribe command"]
  P8RD["plans + payment-methods readers"]
  P8["account-ui hosted composables"]
  BWS["billing-web session + sign-in"]
  BWV["billing-web /v1 surfaces"]
  CORS["cloud PR 9512 ingest CORS + return hosts"]
  PUB["npm publish account-core / billing-contract"]
  P7["Phase 7 host proof: Platform + billing-web live"]
  P6["Phase 6 evidence"]
  S2["Phase 5 slice 2 subscription"]
  FU9["customer-attention predicate"]
  FU11["opaque BillingServerCode"]
  FU12["useCredits clears on SUPERSEDED"]
  P3 --> HD
  FC --> HD
  HD --> RB
  P3 --> SS
  SS --> P7
  RB --> P7
  P3 --> RN
  RN --> PUB
  RB --> PUB
  PUB --> P7
  P3 --> P8PV
  P3 --> P8RD
  P8PV --> P8
  P8RD --> P8
  P4 --> P8
  P8 --> S2
  P8 --> BWS
  BWS --> BWV
  RB --> BWV
  BWV --> P7
  CORS --> P7
  P5 --> P6
  P5 --> WS
  P5 --> FU9
  P3 --> FU11
  P4 --> FU12
  style P3 fill:#d4edda,stroke:#155724
  style P4 fill:#d4edda,stroke:#155724
  style P5 fill:#d4edda,stroke:#155724
  style FC fill:#d4edda,stroke:#155724
  style SS fill:#d4edda,stroke:#155724
  style RB fill:#d4edda,stroke:#155724
  style WS fill:#d4edda,stroke:#155724
  style FU9 fill:#d4edda,stroke:#155724
  style P8PV fill:#d4edda,stroke:#155724
  style BWS stroke:#0366d6,stroke-width:4px
```
dante01yoon added a commit that referenced this pull request Sep 16, 2026
…own-origin session and v1 surfaces (#17799)

Linear FE-2331.

Stacked on #17798 (readers); carries #17797 (previewSubscribe, now on
main) until #17798 lands. #17807 (billing-web own-origin session +
sign-in) and #17809 (billing-web /v1 surfaces) were squash-merged into
this branch, so this PR is the whole Phase 8 view layer: account-ui
composables, the billing-web session/sign-in, and the subscription /
payment-method surfaces.

The plans catalog, the saved cards and the subscription quote are the
three
reads the hosted billing surfaces are built on, and the core now exposes
all
three. Nothing in the view layer could reach them: `BillingClient`
carried only
the balance, capability and status readers, so a host wanting a price
had to
call the core directly and invent its own loading, failure and
cancellation
handling per screen.

- `BillingClient` gains `plans` and `paymentMethods`;
`disposeBillingClient`
disposes both, so a sign-out or workspace switch cannot leave a catalog
or a
  card list serving the previous scope.
- `usePlans` and `usePaymentMethods` follow `useCredits`: seeded from
the
reader's snapshot, `immediate` by default, and a failed refresh keeps
the last
  good value beside the failure rather than blanking the screen.
`usePaymentMethods` also exposes `defaultMethod` and
`invalidateAndRefresh`,
for a host coming back from the payment portal where a card was added or
  removed.
- `usePreviewSubscribe` is on-demand and single-flight: each `quote`
aborts the
one before it through an `AbortController`, and only the latest settles
into
`preview`/`failure`, so a slow price for a plan the user has moved off
never
  lands on screen.
- The app composition root builds both readers and adds them to
`dispose()`,
keeping the two scope-holder lists in step. Commands stay unwired here.

No UI change. These are headless composables; nothing renders them yet.

`usePlans`, `usePaymentMethods` and `usePreviewSubscribe` tests run
against the
real core over the shared billing harness. Both the abort guard and the
payment-methods invalidation were verified to fail when removed. A table
in
`createBillingSdk.test.ts` asserts every reader stops serving the
disposed
scope.

Billing SDK track FE-2210 ([implementation plan
V2](https://app.notion.com/p/3d86d73d36508152b92cdbdfdfe83ac8)). Hybrid
model: top-up in-app, subscription management / invoices / payment
methods on the hosted billing app.

| Phase | Item | Ticket | Status |
| --- | --- | --- | --- |
| 1-2 | Session core, transport, readers | FE-2211/2212/2213 | merged |
| 3 | Operation lifecycle, commands, eight-state projection |
FE-2227/2214/2223 | merged (#17655) |
| 4 | `@comfyorg/account-ui` composables + `CheckoutSteps` | FE-2215 |
merged (#17662, #17663) |
| 5 slice 1 | Top-up through the SDK behind `billing_sdk_topup_enabled`
| FE-2216 | merged (#17665) |
| rollout C | `hosted_billing_destination` server flag read by the host
| FE-2218 | merged (#17716) |
| rollout C | `hostedDestination` port on the lifecycle, value on
operation state | FE-2210/2218 | open (#17783) |
| 7 prep | Scope-source port + credentialed transport (BFF / cookie
hosts) | FE-2218 | merged (#17782) |
| 7 prep | `@comfyorg/account` → `@comfyorg/account-core` rename |
FE-2218 | local, opens after #17783 and #17794 |
| 7 prep | `billing-contract` route builder + `return_to` registry |
FE-2218 | merged (#17795) |
| 3A-3 | Workshop adapter over `createHostedTopupCheckout` | FE-2214 |
merged (#17793) |
| 8 core | `previewSubscribe` command | FE-2331 | merged (#17797) |
| 8 core | Plans + saved payment-methods readers | FE-2331 | open
(#17798) |
| 8 ui | account-ui composables (`usePlans`, `usePaymentMethods`,
`usePreviewSubscribe`) | FE-2331 | **this PR** |
| 7 | billing-web own-origin session, sign-in, SDK composition | FE-2218
| **this PR** (was #17807) |
| 8 ui | billing-web `/v1` entry routing + subscription / payment-method
surfaces | FE-2331 | **this PR** (was #17809) |
| 7 | npm publish (`ingest-types`, `account-core`, `billing-contract`),
Platform install, billing-web live top-up | FE-2218 | todo |
| 6 | Contract tests + live E2E per flow × consumer | FE-2217 | todo |
| 5 slice 2 | Subscription flows through the SDK | FE-2216 | todo
(plan-change decision) |
| follow-up | One `needsCustomerAttention` predicate (from the #17665
review) | FE-2216 | merged (#17792) |
| follow-up | Opaque `BillingServerCode` (from the #17656 review) |
FE-2227 | open (#17794) |
| follow-up | `useCredits` clears on `SUPERSEDED` (from the #17799
review) | FE-2215 | open (#17824) |

```mermaid
flowchart LR
  P3["Phase 3 core lifecycle (merged)"]
  P4["Phase 4 account-ui (merged)"]
  P5["Phase 5 slice 1 top-up flag (merged)"]
  FC["PR 17716 hosted_billing_destination flag (merged)"]
  HD["PR 17783 hostedDestination port"]
  SS["PR 17782 scope-source port + credentialed transport"]
  RN["account-core rename"]
  RB["billing-contract route builder + return_to"]
  WS["Workshop adapter"]
  P8PV["previewSubscribe command"]
  P8RD["plans + payment-methods readers"]
  P8["account-ui hosted composables"]
  BWS["billing-web session + sign-in"]
  BWV["billing-web /v1 surfaces"]
  PUB["npm publish account-core / billing-contract"]
  P7["Phase 7 host proof: Platform + billing-web live"]
  P6["Phase 6 evidence"]
  S2["Phase 5 slice 2 subscription"]
  FU9["customer-attention predicate"]
  FU11["opaque BillingServerCode"]
  FU12["useCredits clears on SUPERSEDED"]
  P3 --> HD
  FC --> HD
  HD --> RB
  P3 --> SS
  SS --> P7
  RB --> P7
  P3 --> RN
  RN --> PUB
  RB --> PUB
  PUB --> P7
  P3 --> P8PV
  P3 --> P8RD
  P8PV --> P8
  P8RD --> P8
  P4 --> P8
  P8 --> S2
  P8 --> BWS
  BWS --> BWV
  RB --> BWV
  BWV --> P7
  P5 --> P6
  P5 --> WS
  P5 --> FU9
  P3 --> FU11
  P4 --> FU12
  style P3 fill:#d4edda,stroke:#155724
  style P4 fill:#d4edda,stroke:#155724
  style P5 fill:#d4edda,stroke:#155724
  style FC fill:#d4edda,stroke:#155724
  style SS fill:#d4edda,stroke:#155724
  style RB fill:#d4edda,stroke:#155724
  style WS fill:#d4edda,stroke:#155724
  style FU9 fill:#d4edda,stroke:#155724
  style P8PV fill:#d4edda,stroke:#155724
  style P8 stroke:#0366d6,stroke-width:4px
  style BWS stroke:#0366d6,stroke-width:4px
  style BWV stroke:#0366d6,stroke-width:4px
```
dante01yoon added a commit that referenced this pull request Sep 16, 2026
…the SDK rail behind billing_sdk_subscription_enabled (#17853)

Stacked on #17783 (base branch
`jaewon/fe-2210-hosted-destination-port`); merge that first.

## Why

Phase 5 slice 1 (#17665) moved top-up onto the Billing SDK behind
`billing_sdk_topup_enabled`. The subscription actions the host already
owns — cancel, resubscribe, and opening the payment portal — still call
the workspace API directly and rely on the legacy poller for settlement
and telemetry. This slice moves those three onto the SDK's commands
behind their own server flag, `billing_sdk_subscription_enabled`
(already on `/api/features` via Comfy-Org/cloud#9248, PostHog at 0%), so
the eight-state lifecycle, idempotency, recovery and telemetry come from
one implementation. Subscribe and plan change are slice 2b, stacked on
this PR.

## How

- **Rail switch.** `billingSdkSubscriptionRailEnabled` =
`billing_sdk_subscription_enabled` AND `unified_cloud_auth`, exactly
like the top-up rail. `useSubscriptionRail()` reads it once,
synchronously, at the start of an action, so a flag flip mid-flow cannot
issue on one rail and observe on the other.
- **Three actions, one adapter.**
`useWorkspaceBilling.cancelSubscription / resubscribe /
manageSubscription` try the rail first; the store runs
`sdk.commands.cancelSubscription()`, `resubscribe()`,
`openPaymentPortal({ returnUrl })` and projects the result onto what the
adapter already does with the legacy calls: settle, or throw a
`WorkspaceApiError` (message is the host's, since the SDK never carries
server text; `serverCode` lands in `.code`). A command that settles in
any phase but `succeeded` is a failure, matching the poller. The refresh
after success mirrors the poller's: cancel → status + balance +
capabilities; resubscribe → `reconcileSubscriptionSuccess` +
capabilities.
- **Fallback.** A 404 (backend gate closed while the client flag is on)
projects to `unavailable`: the adapter runs its legacy body for that
action, and the store latches the route as unavailable for the tab so
later actions go straight to legacy without another failed round trip.
Every other failure — including `SUPERSEDED` — is thrown, never retried
on legacy, so a late or superseded result cannot double-issue.
- **Telemetry.** Lifecycle events are now reported for non-topup
operations (top-up keeps its resumed-only filter because its dialog
reports). `toBillingTelemetryEvent` already emits the poller's payload
shape, so dashboards cannot tell the rails apart.
- **No client-derived server state.** Eligibility and already-held
answers come from the SDK and the server, as for top-up. `subscribe`,
`previewSubscribe`, `useSubscriptionCheckout` and `useLegacyBilling` are
untouched.

## AS-IS / TO-BE

| State | AS-IS (flag off) | TO-BE (flag on) |
| --- | --- | --- |
| Cancel dialog at rest | <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/as-is-cancel-dialog.png">
| <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/to-be-cancel-dialog.png">
|
| Cancel in flight | <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/as-is-cancel-in-flight.png">
| <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/to-be-cancel-in-flight.png">
|
| Cancel settled (success toast) | <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/as-is-cancel-settled.png">
| <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/to-be-cancel-settled.png">
|
| Cancel failed (error toast) | <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/as-is-cancel-failed.png">
| <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/to-be-cancel-failed.png">
|
| User popover after cancel (cancelled state) | <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/as-is-panel-after-cancel.png">
| <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/to-be-panel-after-cancel.png">
|
| Cancel request recorded | <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/as-is-network.png">
| <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/to-be-network.png">
|
| Settings billing panel | <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/as-is-billing-panel.png">
| <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/to-be-billing-panel.png">
|
| Resubscribe (Resume Pro) | <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/as-is-resubscribe.png">
| <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/to-be-resubscribe.png">
|
| Resubscribe request recorded | <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/as-is-resubscribe-network.png">
| <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/to-be-resubscribe-network.png">
|
| Payment-portal request recorded | <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/as-is-portal-network.png">
| <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/to-be-portal-network.png">
|

- AS-IS (flag off): cancel / resubscribe / portal POST the workspace API
directly; settlement and telemetry come from the legacy poller.
- TO-BE (flag on): the same dialogs and toasts, the POSTs go through the
SDK transport (`Idempotency-Key` on the request), settlement through the
operation lifecycle; a 404 falls back to the legacy call.

## Testing

| Gate | Result |
| --- | --- |
| `vitest run src/platform/workspace/billing src/composables/billing
src/platform/workspace/composables src/platform/workspace/stores
src/composables/useFeatureFlags` | 41 files, 1138 tests (12 new
projection tests, 13 new adapter rail tests, +5 store tests) |
| `pnpm typecheck`, `pnpm typecheck:browser`, `lint`, `format:check`,
`knip` | exit 0 |
| `fallow audit --changed-since
origin/jaewon/fe-2210-hosted-destination-port` | no issues in 11 changed
files, complexity 0, duplication 0 |
| Playwright
`browser_tests/tests/dialogs/cancelSubscriptionSdkRail.spec.ts` (cloud
project) | **3 passed** against a served cloud dev build —
`PLAYWRIGHT_TEST_URL=http://localhost:5173 pnpm exec playwright test
--project=cloud
browser_tests/tests/dialogs/cancelSubscriptionSdkRail.spec.ts
--reporter=list`. Flag off → legacy request, flow unchanged; flag on →
SDK request (`Idempotency-Key`), same dialog outcome; flag on + 404 →
legacy fallback. |

## Where this sits in the plan

Billing SDK track FE-2210 ([implementation plan
V2](https://app.notion.com/p/3d86d73d36508152b92cdbdfdfe83ac8)). Hybrid
model: top-up in-app, subscription management / invoices / payment
methods on the hosted billing app.

| Phase | Item | Ticket | Status |
| --- | --- | --- | --- |
| 1-2 | Session core, transport, readers | FE-2211/2212/2213 | merged |
| 3 | Operation lifecycle, commands, eight-state projection |
FE-2227/2214/2223 | merged (#17655) |
| 4 | `@comfyorg/account-ui` composables + `CheckoutSteps` | FE-2215 |
merged (#17662, #17663) |
| 5 slice 1 | Top-up through the SDK behind `billing_sdk_topup_enabled`
| FE-2216 | merged (#17665) |
| rollout C | `hosted_billing_destination` server flag read by the host
| FE-2218 | merged (#17716) |
| rollout C | `hostedDestination` port on the lifecycle, value on
operation state | FE-2210/2218 | #17783 (review; parent of this PR) |
| 7 prep | Scope-source port + credentialed transport (BFF / cookie
hosts) | FE-2218 | merged (#17782) |
| 7 prep | `@comfyorg/account` → `@comfyorg/account-core` rename |
FE-2218 | #17851 (review) |
| 7 prep | `billing-contract` route builder + `return_to` registry |
FE-2218 | merged (#17795) |
| 3A-3 | Workshop adapter over `createHostedTopupCheckout` | FE-2214 |
merged (#17793) |
| 8 core | `previewSubscribe` command | FE-2331 | merged (#17797) |
| 8 core | Plans + saved payment-methods readers | FE-2331 | #17798
(queued) |
| 8 ui | account-ui composables (`usePlans`, `usePaymentMethods`,
`usePreviewSubscribe`) | FE-2331 | #17798 (queued) |
| 7 | billing-web own-origin session, sign-in, SDK composition | FE-2218
| #17798 (queued) |
| 7 | billing-web unit tests in CI (`ci-billing-web-unit.yaml`) |
FE-2218 | merged (#17827); #17844 (queued) |
| 7 | ingest CORS + top-up return hosts for billing.comfy.org and its
previews (Comfy-Org/cloud) | FE-2218 | merged (Comfy-Org/cloud#9512) |
| 8 ui | billing-web `/v1` entry routing + subscription / payment-method
surfaces | FE-2331 | #17798 (queued) |
| 7 | npm publish (`ingest-types`, `account-core`, `billing-contract`),
Platform install, billing-web live top-up | FE-2218 | todo |
| 6 | Contract tests per generated schema (package layer) | FE-2217 |
#17829 (review) |
| 6 | Live E2E per flow × consumer + evidence table | FE-2217 | todo
(needs staging flags) |
| 5 slice 2a | Cancel, resubscribe and payment portal through the SDK
behind `billing_sdk_subscription_enabled` | FE-2216 | **this PR** |
| 5 slice 2b | Subscribe / plan change through the SDK
(`previewSubscribe` quote, then subscribe; the SDK stops
short-circuiting an active plan) | FE-2216 | next, stacked on this PR |
| follow-up | One `needsCustomerAttention` predicate (from the #17665
review) | FE-2216 | merged (#17792) |
| follow-up | Opaque `BillingServerCode` (from the #17656 review) |
FE-2227 | merged (#17794) |
| follow-up | `useCredits` clears on `SUPERSEDED` (from the #17799
review) | FE-2215 | merged (#17824) |
| follow-up | credits / status / capabilities readers fence a late
failure as `SUPERSEDED` (from the #17798 review) | FE-2331 | merged
(#17828) |

```mermaid
flowchart LR
  P3["Phase 3 core lifecycle (merged)"]
  P4["Phase 4 account-ui (merged)"]
  P5["Phase 5 slice 1 top-up flag (merged)"]
  FC["PR 17716 hosted_billing_destination flag (merged)"]
  HD["PR 17783 hostedDestination port"]
  SS["PR 17782 scope-source port + credentialed transport"]
  RN["account-core rename"]
  RB["billing-contract route builder + return_to"]
  WS["Workshop adapter"]
  P8PV["previewSubscribe command"]
  P8RD["plans + payment-methods readers"]
  P8["account-ui hosted composables"]
  BWS["billing-web session + sign-in"]
  BWV["billing-web /v1 surfaces"]
  CORS["cloud PR 9512 ingest CORS + return hosts"]
  PUB["npm publish account-core / billing-contract"]
  P7["Phase 7 host proof: Platform + billing-web live"]
  P6C["Phase 6 contract tests"]
  P6["Phase 6 live evidence"]
  S2A["Phase 5 slice 2a cancel / resubscribe / portal rail"]
  S2B["Phase 5 slice 2b subscribe + plan change"]
  FU9["customer-attention predicate"]
  FU11["opaque BillingServerCode"]
  FU12["useCredits clears on SUPERSEDED"]
  FU13["reader late-failure fence"]
  P3 --> HD
  FC --> HD
  HD --> RB
  P3 --> SS
  SS --> P7
  RB --> P7
  P3 --> RN
  RN --> PUB
  RB --> PUB
  PUB --> P7
  P3 --> P8PV
  P3 --> P8RD
  P8PV --> P8
  P8RD --> P8
  P4 --> P8
  P8 --> S2B
  HD --> S2A
  S2A --> S2B
  P8 --> BWS
  BWS --> BWV
  RB --> BWV
  BWV --> P7
  CORS --> P7
  P5 --> P6
  P3 --> P6C
  P5 --> WS
  P5 --> FU9
  P3 --> FU11
  P4 --> FU12
  P3 --> FU13
  style P3 fill:#d4edda,stroke:#155724
  style P4 fill:#d4edda,stroke:#155724
  style P5 fill:#d4edda,stroke:#155724
  style FC fill:#d4edda,stroke:#155724
  style SS fill:#d4edda,stroke:#155724
  style RB fill:#d4edda,stroke:#155724
  style WS fill:#d4edda,stroke:#155724
  style FU9 fill:#d4edda,stroke:#155724
  style FU11 fill:#d4edda,stroke:#155724
  style FU12 fill:#d4edda,stroke:#155724
  style FU13 fill:#d4edda,stroke:#155724
  style CORS fill:#d4edda,stroke:#155724
  style P8PV fill:#d4edda,stroke:#155724
  style S2A stroke:#0366d6,stroke-width:4px
```
pull Bot pushed a commit to Penguinjanator/ComfyUI_frontend that referenced this pull request Sep 16, 2026
…int one (Comfy-Org#17794)

Linear FE-2227. Follow-up parked from the Comfy-Org#17656 review.

## Why

`BillingFailure.serverCode` is an unbounded server string in a contract
whose
whole point is that server text never reaches a user. Its doc said
"never
render it", but the type said plain `string`, so a command could invent
a code
and compare against it as if the server had sent one.

This closes provenance, not containment. After it, only
`readBillingErrorCode`
can mint a `BillingServerCode`, so a code that reaches a comparison is
one the
server actually sent. The value is still `string` underneath, so
interpolating
it into copy, widening it with `??`, concatenating it or passing it to
`t()`
all still compile — the rendering half of the Comfy-Org#17656 finding stays open,
and
the file comment says so. Full containment is costed in "Not done here"
below.

## How

- `BillingServerCode = string & { readonly [brand]: true }` with a
module-private `unique symbol`, so the brand cannot be forged outside
the
  module that declares it.
- `readBillingErrorCode` is the single producer and the only place the
brand
is minted, at the decode boundary. The brand erases at runtime, so there
is
  no cost.
- Two contract-level helpers bound what a holder can do:
`matchesServerCode`
compares against a code a command names, and `unwrapServerCode` is the
one
widening back to `string`, so every widening is visible at its call
site.
- The four equality comparisons (`topup.ts` `commandFailure`,
`subscriptionCommands.ts` `alreadyInRequestedState`, `mapServerCode`,
and
  the reactivation check) now go through `matchesServerCode`. The named
  constants and their closed sets stay where they were.
- The one host handoff, `topupFailureError` in `topupOperationView.ts`,
calls
`unwrapServerCode` to put the code where `WorkspaceApiError.code`
already
  lives. It is the only widening in the tree.

## AS-IS / TO-BE

No behaviour change; the change is type-level only. AS-IS, any caller
could
write `const code: BillingFailure['serverCode'] = 'NO_PAYMENT_METHOD'`
and
compare against a code no server ever sent. TO-BE that line is a compile
error,
and the only values in the field came through the decode boundary.
Rendering
paths are unchanged in both directions. Every existing test passes with
the
same assertions.

## Not done here

Making the brand genuinely opaque — dropping the `string &` so nothing
reads it
without `unwrapServerCode` — is the containment half, and it is cheapest
now:
`topupOperationView.ts:98` is the only consumer today and it already
calls
`unwrapServerCode`. Measured cost of the switch, from compiling it:
three
errors, all inside the declaring module — `matchesServerCode`'s `===`,
`unwrapServerCode`'s return, and the mint in `billingErrorBody.ts` —
each
needing an `as unknown as` that the current declaration does not. That
tradeoff
(containment bought with double casts in the owning module) is a
deliberate
call, not a default, and Comfy-Org#17798 / Comfy-Org#17799 add consumers this week.
Flagged for a
decision rather than taken here.

## Testing

- New `billingContracts.test.ts`: a table over `matchesServerCode` for a
  matching code, a different code, and a failure with no error body; a
  `@ts-expect-error` case proving a plain string is not assignable to
`serverCode`; and `unwrapServerCode` returning the string the server
sent.
- Fixtures mint codes through `readBillingErrorCode` on a real error
body
  rather than casting, so the test exercises the production decode.
- `pnpm typecheck`, `pnpm lint`, `pnpm format`, `pnpm knip`,
`fallow audit --changed-since origin/main`, and the account, account-ui,
and
  `src/platform/workspace/billing` suites all pass.
## Where this sits in the plan

Billing SDK track FE-2210 ([implementation plan
V2](https://app.notion.com/p/3d86d73d36508152b92cdbdfdfe83ac8)). Hybrid
model: top-up in-app, subscription management / invoices / payment
methods on the hosted billing app.

| Phase | Item | Ticket | Status |
| --- | --- | --- | --- |
| 1-2 | Session core, transport, readers | FE-2211/2212/2213 | merged |
| 3 | Operation lifecycle, commands, eight-state projection |
FE-2227/2214/2223 | merged (Comfy-Org#17655) |
| 4 | `@comfyorg/account-ui` composables + `CheckoutSteps` | FE-2215 |
merged (Comfy-Org#17662, Comfy-Org#17663) |
| 5 slice 1 | Top-up through the SDK behind `billing_sdk_topup_enabled`
| FE-2216 | merged (Comfy-Org#17665) |
| rollout C | `hosted_billing_destination` server flag read by the host
| FE-2218 | merged (Comfy-Org#17716) |
| rollout C | `hostedDestination` port on the lifecycle, value on
operation state | FE-2210/2218 | open (Comfy-Org#17783) |
| 7 prep | Scope-source port + credentialed transport (BFF / cookie
hosts) | FE-2218 | open (Comfy-Org#17782) |
| 7 prep | `@comfyorg/account` → `@comfyorg/account-core` rename |
FE-2218 | local, opens after Comfy-Org#17782 and Comfy-Org#17783 |
| 7 prep | `billing-contract` route builder + `return_to` registry |
FE-2218 | in progress |
| 3A-3 | Workshop adapter over `createHostedTopupCheckout` | FE-2214 |
open (Comfy-Org#17793) |
| 8 | `previewSubscribe`, plans, payment-methods readers + account-ui +
billing-web views | FE-2331 | todo |
| 7 | npm publish (`ingest-types`, `account-core`, `billing-contract`),
Platform install, billing-web live top-up | FE-2218 | todo |
| 6 | Contract tests + live E2E per flow × consumer | FE-2217 | todo |
| 5 slice 2 | Subscription flows through the SDK | FE-2216 | todo
(plan-change decision) |
| follow-up | One `needsCustomerAttention` predicate (from the Comfy-Org#17665
review) | FE-2216 | open (Comfy-Org#17792) |
| follow-up | Unforgeable `BillingServerCode` (from the Comfy-Org#17656 review) |
FE-2227 | **this PR** |

```mermaid
flowchart LR
  P3["Phase 3 core lifecycle (merged)"]
  P4["Phase 4 account-ui (merged)"]
  P5["Phase 5 slice 1 top-up flag (merged)"]
  FC["PR 17716 hosted_billing_destination flag (merged)"]
  HD["PR 17783 hostedDestination port"]
  SS["PR 17782 scope-source port + credentialed transport"]
  RN["account-core rename"]
  RB["billing-contract route builder + return_to"]
  WS["Workshop adapter"]
  P8["Phase 8 readers + billing-web views"]
  PUB["npm publish account-core / billing-contract"]
  P7["Phase 7 host proof: Platform + billing-web live"]
  P6["Phase 6 evidence"]
  S2["Phase 5 slice 2 subscription"]
  FU9["customer-attention predicate"]
  FU11["unforgeable BillingServerCode"]
  P3 --> HD
  FC --> HD
  HD --> RB
  P3 --> SS
  SS --> P7
  RB --> P7
  P3 --> RN
  RN --> PUB
  RB --> PUB
  PUB --> P7
  P4 --> P8
  P8 --> S2
  P5 --> P6
  P5 --> WS
  P5 --> FU9
  P3 --> FU11
  style P3 fill:#d4edda,stroke:#155724
  style P4 fill:#d4edda,stroke:#155724
  style P5 fill:#d4edda,stroke:#155724
  style FC fill:#d4edda,stroke:#155724
  style FU11 stroke:#0366d6,stroke-width:4px
```
pull Bot pushed a commit to Penguinjanator/ComfyUI_frontend that referenced this pull request Sep 16, 2026
…ders, hosted composables, own-origin session and v1 surfaces (Comfy-Org#17798)

Linear FE-2331 / FE-2218.

This PR is the whole Phase 8 view layer after the stack was
consolidated: Comfy-Org#17799 (account-ui `usePlans` / `usePaymentMethods` /
`usePreviewSubscribe` + app-root readers), Comfy-Org#17807 (billing-web
own-origin session, sign-in, SDK composition) and Comfy-Org#17809 (billing-web
`/v1` entry routing, subscription and payment-method surfaces) were
squash-merged into this branch; their bodies, decisions and screenshots
remain on those PRs. Rebased onto main after Comfy-Org#17782 (scopeSource),
Comfy-Org#17795 (billing-contract) and Comfy-Org#17797 (previewSubscribe) landed, so none
of that content is in this diff.

## Why

Phase 8's hosted billing surfaces render plan management and saved
payment
methods, and both reads have to go through the billing SDK so they
inherit the
scope tracking, deduplication, and coded failures the other readers
already
have. The generated schemas for both routes exist, so nothing has to be
hand-declared.

## How

- `plans.ts`: `createPlansReader` over `GET /billing/plans`, decoded
with
`zGetBillingPlansResponse`. No freshness window — the catalog carries no
  declared lifetime, so the host decides when to re-read.
- `paymentMethods.ts`: `createPaymentMethodsReader` over
  `GET /billing/payment-methods`, decoded with
`zListSavedPaymentMethodsResponse`, plus `invalidate()` so a host
returning
from the payment portal can drop the list it holds without a scope
change.
- Both follow the existing reader shape exactly:
`createBillingScopeTracker`
drops the snapshot and any in-flight read on a scope change, concurrent
reads
  for one scope share a single request, a 2xx that fails the schema is
`MALFORMED_RESPONSE`, and HTTP failures map through `codeForHttpStatus`.
- Exported from `@comfyorg/account/billing` alongside the credits,
status, and
  capabilities readers.

The four readers now share the same request/publish body, which `fallow
audit`
reports as a duplication warning. Factoring it out would touch
`credits.ts` and
`status.ts`, which two open PRs already modify, so it is left for a
follow-up.

## AS-IS / TO-BE

No UI change. The cloud app still calls `workspaceApi.getBillingPlans`
and
`workspaceApi.listSavedPaymentMethods`; the composables and host wiring
that
move it onto these readers land in separate PRs.

## Testing

`plans.test.ts` and `paymentMethods.test.ts` cover the decode and scope
of a
successful read, the caller timeout reaching the request, deduplication
of
concurrent reads, a scope change in flight reporting `SUPERSEDED` with
nothing
cached, a signed-out reader reporting `NOT_AUTHENTICATED` without a
request, the
HTTP status table (401 replayed and unreplayed, 403, 404, 500), a
malformed 2xx,
and `dispose`. Payment methods additionally cover the empty list and
`invalidate` dropping the snapshot so the next read refetches.

`pnpm typecheck`, `pnpm lint`, `pnpm format`, `pnpm knip`, and
`fallow audit --changed-since origin/main` pass.

Follow-up, not in this PR: the four readers now share a 32-line
scope/in-flight skeleton (`credits.ts`, `status.ts`, `plans.ts`,
`paymentMethods.ts`; fallow reports it as one clone family). Comfy-Org#17782 has
landed, but extracting it still touches files Comfy-Org#17794 is changing, so it
waits for that to land.

## Where this sits in the plan

Billing SDK track FE-2210 ([implementation plan
V2](https://app.notion.com/p/3d86d73d36508152b92cdbdfdfe83ac8)). Hybrid
model: top-up in-app, subscription management / invoices / payment
methods on the hosted billing app.

| Phase | Item | Ticket | Status |
| --- | --- | --- | --- |
| 1-2 | Session core, transport, readers | FE-2211/2212/2213 | merged |
| 3 | Operation lifecycle, commands, eight-state projection |
FE-2227/2214/2223 | merged (Comfy-Org#17655) |
| 4 | `@comfyorg/account-ui` composables + `CheckoutSteps` | FE-2215 |
merged (Comfy-Org#17662, Comfy-Org#17663) |
| 5 slice 1 | Top-up through the SDK behind `billing_sdk_topup_enabled`
| FE-2216 | merged (Comfy-Org#17665) |
| rollout C | `hosted_billing_destination` server flag read by the host
| FE-2218 | merged (Comfy-Org#17716) |
| rollout C | `hostedDestination` port on the lifecycle, value on
operation state | FE-2210/2218 | open (Comfy-Org#17783) |
| 7 prep | Scope-source port + credentialed transport (BFF / cookie
hosts) | FE-2218 | merged (Comfy-Org#17782) |
| 7 prep | `@comfyorg/account` → `@comfyorg/account-core` rename |
FE-2218 | local, opens after Comfy-Org#17783 and Comfy-Org#17794 |
| 7 prep | `billing-contract` route builder + `return_to` registry |
FE-2218 | merged (Comfy-Org#17795) |
| 3A-3 | Workshop adapter over `createHostedTopupCheckout` | FE-2214 |
merged (Comfy-Org#17793) |
| 8 core | `previewSubscribe` command | FE-2331 | merged (Comfy-Org#17797) |
| 8 core | Plans + saved payment-methods readers | FE-2331 | **this PR**
|
| 8 ui | account-ui composables (`usePlans`, `usePaymentMethods`,
`usePreviewSubscribe`) | FE-2331 | **this PR** (was Comfy-Org#17799) |
| 7 | billing-web own-origin session, sign-in, SDK composition | FE-2218
| **this PR** (was Comfy-Org#17807) |
| 8 ui | billing-web `/v1` entry routing + subscription / payment-method
surfaces | FE-2331 | **this PR** (was Comfy-Org#17809) |
| 7 | npm publish (`ingest-types`, `account-core`, `billing-contract`),
Platform install, billing-web live top-up | FE-2218 | todo |
| 6 | Contract tests + live E2E per flow × consumer | FE-2217 | todo |
| 5 slice 2 | Subscription flows through the SDK | FE-2216 | todo
(plan-change decision) |
| follow-up | One `needsCustomerAttention` predicate (from the Comfy-Org#17665
review) | FE-2216 | merged (Comfy-Org#17792) |
| follow-up | Opaque `BillingServerCode` (from the Comfy-Org#17656 review) |
FE-2227 | open (Comfy-Org#17794) |
| follow-up | `useCredits` clears on `SUPERSEDED` (from the Comfy-Org#17799
review) | FE-2215 | open (Comfy-Org#17824) |

```mermaid
flowchart LR
  P3["Phase 3 core lifecycle (merged)"]
  P4["Phase 4 account-ui (merged)"]
  P5["Phase 5 slice 1 top-up flag (merged)"]
  FC["PR 17716 hosted_billing_destination flag (merged)"]
  HD["PR 17783 hostedDestination port"]
  SS["PR 17782 scope-source port + credentialed transport"]
  RN["account-core rename"]
  RB["billing-contract route builder + return_to"]
  WS["Workshop adapter"]
  P8PV["previewSubscribe command"]
  P8RD["plans + payment-methods readers"]
  P8["account-ui hosted composables"]
  BWS["billing-web session + sign-in"]
  BWV["billing-web /v1 surfaces"]
  PUB["npm publish account-core / billing-contract"]
  P7["Phase 7 host proof: Platform + billing-web live"]
  P6["Phase 6 evidence"]
  S2["Phase 5 slice 2 subscription"]
  FU9["customer-attention predicate"]
  FU11["opaque BillingServerCode"]
  FU12["useCredits clears on SUPERSEDED"]
  P3 --> HD
  FC --> HD
  HD --> RB
  P3 --> SS
  SS --> P7
  RB --> P7
  P3 --> RN
  RN --> PUB
  RB --> PUB
  PUB --> P7
  P3 --> P8PV
  P3 --> P8RD
  P8PV --> P8
  P8RD --> P8
  P4 --> P8
  P8 --> S2
  P8 --> BWS
  BWS --> BWV
  RB --> BWV
  BWV --> P7
  P5 --> P6
  P5 --> WS
  P5 --> FU9
  P3 --> FU11
  P4 --> FU12
  style P3 fill:#d4edda,stroke:#155724
  style P4 fill:#d4edda,stroke:#155724
  style P5 fill:#d4edda,stroke:#155724
  style FC fill:#d4edda,stroke:#155724
  style SS fill:#d4edda,stroke:#155724
  style RB fill:#d4edda,stroke:#155724
  style WS fill:#d4edda,stroke:#155724
  style FU9 fill:#d4edda,stroke:#155724
  style P8PV fill:#d4edda,stroke:#155724
  style P8RD stroke:#0366d6,stroke-width:4px
  style P8 stroke:#0366d6,stroke-width:4px
  style BWS stroke:#0366d6,stroke-width:4px
  style BWV stroke:#0366d6,stroke-width:4px
```
pull Bot pushed a commit to Penguinjanator/ComfyUI_frontend that referenced this pull request Sep 16, 2026
… a status (Comfy-Org#17844)

Follow-up to Comfy-Org#17827, from @huang47's review.

## Why

Two of the three review points, both in files Comfy-Org#17827 touched.

**1. The workflow does not gate on itself**
([comment](Comfy-Org#17827 (comment))).
`app_billing_web` listed only `apps/billing-web/**`, so a PR that
changes nothing but `ci-billing-web-unit.yaml` leaves `billing-web-unit`
skipped and `billing-web-unit-gate` passing through its skip branch.
Comfy-Org#17827 merged exactly that way — run
[35103654481](https://github.com/Comfy-Org/ComfyUI_frontend/actions/runs/35103654481)
never executed the job it added. Only the post-merge push run on `main`
([35121739924](https://github.com/Comfy-Org/ComfyUI_frontend/actions/runs/35121739924))
did, because every filter output defaults to `'true'` off
`pull_request`.

**2. The flag has no status of its own**
([comment](Comfy-Org#17827 (comment))).
`codecov.yml` declared the `billing-web` flag but no
`project.billing-web` / `patch.billing-web` under `coverage.status`,
while the website flag has both. The upload arrived with nothing
attributing it, which is why Comfy-Org#17827 showed live `codecov/patch/website`
and `codecov/project/website` checks and no billing-web counterparts.

## How

- `app_billing_web` now lists
`.github/workflows/ci-billing-web-unit.yaml`, the way `app_website`
lists `ci-website-e2e.yaml` and its two scripts. Output description
updated to match.
- `project.billing-web` and `patch.billing-web` mirror the website
entries verbatim apart from the path and flag: scoped to
`apps/billing-web/src/**`, `informational: true`,
`flag_coverage_not_uploaded_behavior: pass`, so a skipped job does not
fail the status.

## Also in this PR (added after the first push)

**The flag rename** (`billing-web` → `billing-web-unit`, @huang47's
third point) landed as a second commit, 089a852. It changes `flags:`
in `ci-billing-web-unit.yaml`, the `flags:` list of both new status
entries and the `flags.` block in `codecov.yml` in one commit, so the
upload and the config never disagree. The status keys stay `billing-web`
(check names `codecov/project/billing-web`,
`codecov/patch/billing-web`), mirroring how the website keeps status key
`website` with flag `website-unit`. The first push could not include it
because that session's token lacked the `workflow` scope; this push has
it.

Deliberately unchanged: `app_website` still does **not** list
`ci-website-unit.yaml` (only the e2e workflow and its two scripts), so
the website *unit* workflow keeps the blind spot this PR fixes for
billing-web. @huang47 — worth the matching one-liner, or do you want the
asymmetry left alone?

## AS-IS / TO-BE

No UI change; CI configuration only.

- AS-IS: a `ci-billing-web-unit.yaml`-only PR skips the suite and
reports a green gate. The `billing-web` flag uploads with no dedicated
status.
- TO-BE: that PR runs the suite. The upload gets
`codecov/project/billing-web` and `codecov/patch/billing-web`.

## Testing

- `curl -X POST --data-binary @codecov.yml https://codecov.io/validate`
→ `Valid!`. Both new statuses resolve to flag `billing-web` and path
`(?s:apps/billing\-web/src/.*)\Z`.
- Cross-checked the three places the flag name appears — the workflow's
`flags:`, `flags.billing-web`, and both status entries — all read
`billing-web`, so the upload is attributed.
- Both changed files parse as YAML; `app_billing_web` resolves to
`['apps/billing-web/**', '.github/workflows/ci-billing-web-unit.yaml']`.
- Not demonstrated end-to-end: this PR touches neither
`apps/billing-web/**` nor the workflow, so `billing-web-unit` is
expected to **skip** here too. The self-test behaviour can only be
observed on a PR that edits the workflow file, which is the push this
token cannot make. The mechanism is the same glob matching that already
makes `app_website` react to `ci-website-e2e.yaml`.

## Where this sits in the plan

Billing SDK track FE-2210 ([implementation plan
V2](https://app.notion.com/p/3d86d73d36508152b92cdbdfdfe83ac8)). Hybrid
model: top-up in-app, subscription management / invoices / payment
methods on the hosted billing app.

| Phase | Item | Ticket | Status |
| --- | --- | --- | --- |
| 1-2 | Session core, transport, readers | FE-2211/2212/2213 | merged |
| 3 | Operation lifecycle, commands, eight-state projection |
FE-2227/2214/2223 | merged (Comfy-Org#17655) |
| 4 | `@comfyorg/account-ui` composables + `CheckoutSteps` | FE-2215 |
merged (Comfy-Org#17662, Comfy-Org#17663) |
| 5 slice 1 | Top-up through the SDK behind `billing_sdk_topup_enabled`
| FE-2216 | merged (Comfy-Org#17665) |
| rollout C | `hosted_billing_destination` server flag read by the host
| FE-2218 | merged (Comfy-Org#17716) |
| rollout C | `hostedDestination` port on the lifecycle, value on
operation state | FE-2210/2218 | Comfy-Org#17783 (review) |
| 7 prep | Scope-source port + credentialed transport (BFF / cookie
hosts) | FE-2218 | merged (Comfy-Org#17782) |
| 7 prep | `@comfyorg/account` → `@comfyorg/account-core` rename |
FE-2218 | todo (after Comfy-Org#17783, Comfy-Org#17794) |
| 7 prep | `billing-contract` route builder + `return_to` registry |
FE-2218 | merged (Comfy-Org#17795) |
| 3A-3 | Workshop adapter over `createHostedTopupCheckout` | FE-2214 |
merged (Comfy-Org#17793) |
| 8 core | `previewSubscribe` command | FE-2331 | merged (Comfy-Org#17797) |
| 8 core | Plans + saved payment-methods readers | FE-2331 | Comfy-Org#17798
(review) |
| 8 ui | account-ui composables (`usePlans`, `usePaymentMethods`,
`usePreviewSubscribe`) | FE-2331 | Comfy-Org#17798 (review) |
| 7 | billing-web own-origin session, sign-in, SDK composition | FE-2218
| Comfy-Org#17798 (review) |
| 7 | billing-web unit tests in CI (`ci-billing-web-unit.yaml`) |
FE-2218 | merged (Comfy-Org#17827); **this PR** (Comfy-Org#17844) self-tests the workflow
and adds the flag statuses |
| 7 | ingest CORS + top-up return hosts for billing.comfy.org and its
previews (Comfy-Org/cloud) | FE-2218 | Comfy-Org/cloud#9512 (approved
x2, CI rerun) |
| 8 ui | billing-web `/v1` entry routing + subscription / payment-method
surfaces | FE-2331 | Comfy-Org#17798 (review) |
| 7 | npm publish (`ingest-types`, `account-core`, `billing-contract`),
Platform install, billing-web live top-up | FE-2218 | todo |
| 6 | Contract tests per generated schema (package layer) | FE-2217 |
Comfy-Org#17829 (review) |
| 6 | Live E2E per flow × consumer + evidence table | FE-2217 | todo
(needs staging flags) |
| 5 slice 2 | Subscription flows through the SDK | FE-2216 | todo
(plan-change decision) |
| follow-up | One `needsCustomerAttention` predicate (from the Comfy-Org#17665
review) | FE-2216 | merged (Comfy-Org#17792) |
| follow-up | Opaque `BillingServerCode` (from the Comfy-Org#17656 review) |
FE-2227 | Comfy-Org#17794 (review) |
| follow-up | `useCredits` clears on `SUPERSEDED` (from the Comfy-Org#17799
review) | FE-2215 | merged (Comfy-Org#17824) |
| follow-up | credits / status / capabilities readers fence a late
failure as `SUPERSEDED` (from the Comfy-Org#17798 review) | FE-2331 | merged
(Comfy-Org#17828) |

```mermaid
flowchart LR
  P3["Phase 3 core lifecycle (merged)"]
  P4["Phase 4 account-ui (merged)"]
  P5["Phase 5 slice 1 top-up flag (merged)"]
  FC["PR 17716 hosted_billing_destination flag (merged)"]
  HD["PR 17783 hostedDestination port"]
  SS["PR 17782 scope-source port + credentialed transport"]
  RN["account-core rename"]
  RB["billing-contract route builder + return_to"]
  WS["Workshop adapter"]
  P8PV["previewSubscribe command"]
  P8RD["plans + payment-methods readers"]
  P8["account-ui hosted composables"]
  BWS["billing-web session + sign-in"]
  BWV["billing-web /v1 surfaces"]
  CORS["cloud PR 9512 ingest CORS + return hosts"]
  PUB["npm publish account-core / billing-contract"]
  P7["Phase 7 host proof: Platform + billing-web live"]
  CI["billing-web unit CI: PR 17827 (merged) + PR 17844 follow-up"]
  P6C["Phase 6 contract tests"]
  P6["Phase 6 live evidence"]
  S2["Phase 5 slice 2 subscription"]
  FU9["customer-attention predicate"]
  FU11["opaque BillingServerCode"]
  FU12["useCredits clears on SUPERSEDED"]
  FU13["reader late-failure fence"]
  P3 --> HD
  FC --> HD
  HD --> RB
  P3 --> SS
  SS --> P7
  RB --> P7
  P3 --> RN
  RN --> PUB
  RB --> PUB
  PUB --> P7
  P3 --> P8PV
  P3 --> P8RD
  P8PV --> P8
  P8RD --> P8
  P4 --> P8
  P8 --> S2
  P8 --> BWS
  BWS --> BWV
  RB --> BWV
  BWV --> P7
  CORS --> P7
  BWS --> CI
  CI --> P7
  P5 --> P6
  P3 --> P6C
  P5 --> WS
  P5 --> FU9
  P3 --> FU11
  P4 --> FU12
  P3 --> FU13
  style P3 fill:#d4edda,stroke:#155724
  style P4 fill:#d4edda,stroke:#155724
  style P5 fill:#d4edda,stroke:#155724
  style FC fill:#d4edda,stroke:#155724
  style SS fill:#d4edda,stroke:#155724
  style RB fill:#d4edda,stroke:#155724
  style WS fill:#d4edda,stroke:#155724
  style FU9 fill:#d4edda,stroke:#155724
  style P8PV fill:#d4edda,stroke:#155724
  style CI stroke:#0366d6,stroke-width:4px
```
pull Bot pushed a commit to Penguinjanator/ComfyUI_frontend that referenced this pull request Sep 16, 2026
… billing reads (Comfy-Org#17852)

Stacked on Comfy-Org#17798 (base branch
`jaewon/fe-2331-plans-payment-methods-readers`); merge that first.
Comfy-Org#17851 (the `account-core` rename) sits on the same parent: whichever of
the two lands second is re-based mechanically (the rename has a replay
script).

## Why

`fallow audit` on Comfy-Org#17798 reported a clone family across the five billing
readers: `credits.ts`, `status.ts`, `capabilities.ts`, `plans.ts` and
`paymentMethods.ts` each re-implemented the same fetch-and-fence shape —
capture the scope, share one request per scope, release a caller on its
own signal, report a late answer (success or failure) as `SUPERSEDED`,
and drop a published snapshot on a denial unless the request predates a
change the host fenced. Five copies of that logic is five places the
Comfy-Org#17828 late-failure fence had to be applied, and the next reader would
have been a sixth.

## How

One skeleton, `createScopedReader`, owns the request sharing, the caller
release, the publish fence and the denial drop. A reader supplies only
its route, decoder (`parse`) and projection into a snapshot, plus two
optional hooks that absorb the real variants: `cached` (capabilities'
freshness window) and `publish` (payment-methods' fenced list,
capabilities' publish-as-stale). `setSnapshot` and `fenceInFlight({
detach })` let each reader assemble its own `invalidate` — capabilities
fences without detaching, payment methods fences and detaches.

The public API of every reader is unchanged in shape and semantics:
`index.ts` is untouched and no consumer in `account-ui`, `billing-web`
or `src/platform/workspace/billing` changed. Per-reader production size:
credits 158→80, status 137→64, plans 163→78, paymentMethods 197→94,
capabilities 317→235 lines.

Tests: the fence family is proven once in `scopedReader.test.ts` with a
five-reader case table (sparse filters for the one reader that paces
itself), and each reader keeps only the tests of its own projection —
capabilities' freshness, denials, revision invalidation and
`resolved_for` checks; payment-methods' three invalidation cases.
Coverage went up: status gained the signed-out-in-flight case, plans and
payment methods gained dispose, all five gained sign-out-then-read.

## AS-IS / TO-BE

No user-facing change; core package internals only.

- AS-IS: five readers, each with its own copy of the scope fence; fallow
reports 2 clone groups / 46 lines across three of them plus 4 groups
spanning all four non-paced readers.
- TO-BE: one skeleton, five thin readers; `fallow audit --changed-since
<parent>` reports duplication 0 and no clone group above the 3-instance
threshold.

## Testing

| Gate | Result |
| --- | --- |
| `packages/account` vitest | 42 files, 659 tests (67 new shared cases
replace 82 per-reader copies) |
| `packages/account-ui` vitest | 9 files, 41 tests |
| `@comfyorg/billing-web` test:unit | 10 files, 90 tests |
| `pnpm typecheck`, `lint`, `format`, `knip` | exit 0 |
| `fallow audit --changed-since
origin/jaewon/fe-2331-plans-payment-methods-readers` | no issues in 13
changed files |

## Where this sits in the plan

Billing SDK track FE-2210 ([implementation plan
V2](https://app.notion.com/p/3d86d73d36508152b92cdbdfdfe83ac8)). Hybrid
model: top-up in-app, subscription management / invoices / payment
methods on the hosted billing app.

| Phase | Item | Ticket | Status |
| --- | --- | --- | --- |
| 1-2 | Session core, transport, readers | FE-2211/2212/2213 | merged |
| 3 | Operation lifecycle, commands, eight-state projection |
FE-2227/2214/2223 | merged (Comfy-Org#17655) |
| 4 | `@comfyorg/account-ui` composables + `CheckoutSteps` | FE-2215 |
merged (Comfy-Org#17662, Comfy-Org#17663) |
| 5 slice 1 | Top-up through the SDK behind `billing_sdk_topup_enabled`
| FE-2216 | merged (Comfy-Org#17665) |
| rollout C | `hosted_billing_destination` server flag read by the host
| FE-2218 | merged (Comfy-Org#17716) |
| rollout C | `hostedDestination` port on the lifecycle, value on
operation state | FE-2210/2218 | Comfy-Org#17783 (review) |
| 7 prep | Scope-source port + credentialed transport (BFF / cookie
hosts) | FE-2218 | merged (Comfy-Org#17782) |
| 7 prep | `@comfyorg/account` → `@comfyorg/account-core` rename |
FE-2218 | Comfy-Org#17851 (review, sibling of this PR on Comfy-Org#17798) |
| 7 prep | `billing-contract` route builder + `return_to` registry |
FE-2218 | merged (Comfy-Org#17795) |
| 3A-3 | Workshop adapter over `createHostedTopupCheckout` | FE-2214 |
merged (Comfy-Org#17793) |
| 8 core | `previewSubscribe` command | FE-2331 | merged (Comfy-Org#17797) |
| 8 core | Plans + saved payment-methods readers | FE-2331 | Comfy-Org#17798
(review) |
| 8 ui | account-ui composables (`usePlans`, `usePaymentMethods`,
`usePreviewSubscribe`) | FE-2331 | Comfy-Org#17798 (review) |
| 7 | billing-web own-origin session, sign-in, SDK composition | FE-2218
| Comfy-Org#17798 (review) |
| 7 | billing-web unit tests in CI (`ci-billing-web-unit.yaml`) |
FE-2218 | merged (Comfy-Org#17827); Comfy-Org#17844 follow-up (review) |
| 7 | ingest CORS + top-up return hosts for billing.comfy.org and its
previews (Comfy-Org/cloud) | FE-2218 | merged (Comfy-Org/cloud#9512) |
| 8 ui | billing-web `/v1` entry routing + subscription / payment-method
surfaces | FE-2331 | Comfy-Org#17798 (review) |
| 7 | npm publish (`ingest-types`, `account-core`, `billing-contract`),
Platform install, billing-web live top-up | FE-2218 | todo |
| 6 | Contract tests per generated schema (package layer) | FE-2217 |
Comfy-Org#17829 (review) |
| 6 | Live E2E per flow × consumer + evidence table | FE-2217 | todo
(needs staging flags) |
| 5 slice 2 | Subscription flows through the SDK | FE-2216 | todo
(plan-change decision) |
| follow-up | One `needsCustomerAttention` predicate (from the Comfy-Org#17665
review) | FE-2216 | merged (Comfy-Org#17792) |
| follow-up | Opaque `BillingServerCode` (from the Comfy-Org#17656 review) |
FE-2227 | merged (Comfy-Org#17794) |
| follow-up | `useCredits` clears on `SUPERSEDED` (from the Comfy-Org#17799
review) | FE-2215 | merged (Comfy-Org#17824) |
| follow-up | credits / status / capabilities readers fence a late
failure as `SUPERSEDED` (from the Comfy-Org#17798 review) | FE-2331 | merged
(Comfy-Org#17828) |
| follow-up | one scoped-reader skeleton behind the five billing reads
(from the Comfy-Org#17798 fallow report) | FE-2331 | **this PR** |

```mermaid
flowchart LR
  P3["Phase 3 core lifecycle (merged)"]
  P4["Phase 4 account-ui (merged)"]
  P5["Phase 5 slice 1 top-up flag (merged)"]
  FC["PR 17716 hosted_billing_destination flag (merged)"]
  HD["PR 17783 hostedDestination port"]
  SS["PR 17782 scope-source port + credentialed transport"]
  RN["account-core rename"]
  RB["billing-contract route builder + return_to"]
  WS["Workshop adapter"]
  P8PV["previewSubscribe command"]
  P8RD["plans + payment-methods readers"]
  P8["account-ui hosted composables"]
  BWS["billing-web session + sign-in"]
  BWV["billing-web /v1 surfaces"]
  CORS["cloud PR 9512 ingest CORS + return hosts"]
  PUB["npm publish account-core / billing-contract"]
  P7["Phase 7 host proof: Platform + billing-web live"]
  P6C["Phase 6 contract tests"]
  P6["Phase 6 live evidence"]
  S2["Phase 5 slice 2 subscription"]
  FU9["customer-attention predicate"]
  FU11["opaque BillingServerCode"]
  FU12["useCredits clears on SUPERSEDED"]
  FU13["reader late-failure fence"]
  FU14["scoped reader skeleton"]
  P3 --> HD
  FC --> HD
  HD --> RB
  P3 --> SS
  SS --> P7
  RB --> P7
  P3 --> RN
  RN --> PUB
  RB --> PUB
  PUB --> P7
  P3 --> P8PV
  P3 --> P8RD
  P8PV --> P8
  P8RD --> P8
  P4 --> P8
  P8 --> S2
  P8 --> BWS
  BWS --> BWV
  RB --> BWV
  BWV --> P7
  CORS --> P7
  P5 --> P6
  P3 --> P6C
  P5 --> WS
  P5 --> FU9
  P3 --> FU11
  P4 --> FU12
  P3 --> FU13
  P8RD --> FU14
  FU13 --> FU14
  style P3 fill:#d4edda,stroke:#155724
  style P4 fill:#d4edda,stroke:#155724
  style P5 fill:#d4edda,stroke:#155724
  style FC fill:#d4edda,stroke:#155724
  style SS fill:#d4edda,stroke:#155724
  style RB fill:#d4edda,stroke:#155724
  style WS fill:#d4edda,stroke:#155724
  style FU9 fill:#d4edda,stroke:#155724
  style FU11 fill:#d4edda,stroke:#155724
  style FU12 fill:#d4edda,stroke:#155724
  style FU13 fill:#d4edda,stroke:#155724
  style CORS fill:#d4edda,stroke:#155724
  style P8PV fill:#d4edda,stroke:#155724
  style FU14 stroke:#0366d6,stroke-width:4px
```
dante01yoon added a commit that referenced this pull request Sep 17, 2026
…the SDK rail behind billing_sdk_subscription_enabled (#17853)

Stacked on #17783 (base branch
`jaewon/fe-2210-hosted-destination-port`); merge that first.

Phase 5 slice 1 (#17665) moved top-up onto the Billing SDK behind
`billing_sdk_topup_enabled`. The subscription actions the host already
owns — cancel, resubscribe, and opening the payment portal — still call
the workspace API directly and rely on the legacy poller for settlement
and telemetry. This slice moves those three onto the SDK's commands
behind their own server flag, `billing_sdk_subscription_enabled`
(already on `/api/features` via Comfy-Org/cloud#9248, PostHog at 0%), so
the eight-state lifecycle, idempotency, recovery and telemetry come from
one implementation. Subscribe and plan change are slice 2b, stacked on
this PR.

- **Rail switch.** `billingSdkSubscriptionRailEnabled` =
`billing_sdk_subscription_enabled` AND `unified_cloud_auth`, exactly
like the top-up rail. `useSubscriptionRail()` reads it once,
synchronously, at the start of an action, so a flag flip mid-flow cannot
issue on one rail and observe on the other.
- **Three actions, one adapter.**
`useWorkspaceBilling.cancelSubscription / resubscribe /
manageSubscription` try the rail first; the store runs
`sdk.commands.cancelSubscription()`, `resubscribe()`,
`openPaymentPortal({ returnUrl })` and projects the result onto what the
adapter already does with the legacy calls: settle, or throw a
`WorkspaceApiError` (message is the host's, since the SDK never carries
server text; `serverCode` lands in `.code`). A command that settles in
any phase but `succeeded` is a failure, matching the poller. The refresh
after success mirrors the poller's: cancel → status + balance +
capabilities; resubscribe → `reconcileSubscriptionSuccess` +
capabilities.
- **Fallback.** A 404 (backend gate closed while the client flag is on)
projects to `unavailable`: the adapter runs its legacy body for that
action, and the store latches the route as unavailable for the tab so
later actions go straight to legacy without another failed round trip.
Every other failure — including `SUPERSEDED` — is thrown, never retried
on legacy, so a late or superseded result cannot double-issue.
- **Telemetry.** Lifecycle events are now reported for non-topup
operations (top-up keeps its resumed-only filter because its dialog
reports). `toBillingTelemetryEvent` already emits the poller's payload
shape, so dashboards cannot tell the rails apart.
- **No client-derived server state.** Eligibility and already-held
answers come from the SDK and the server, as for top-up. `subscribe`,
`previewSubscribe`, `useSubscriptionCheckout` and `useLegacyBilling` are
untouched.

| State | AS-IS (flag off) | TO-BE (flag on) |
| --- | --- | --- |
| Cancel dialog at rest | <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/as-is-cancel-dialog.png">
| <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/to-be-cancel-dialog.png">
|
| Cancel in flight | <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/as-is-cancel-in-flight.png">
| <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/to-be-cancel-in-flight.png">
|
| Cancel settled (success toast) | <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/as-is-cancel-settled.png">
| <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/to-be-cancel-settled.png">
|
| Cancel failed (error toast) | <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/as-is-cancel-failed.png">
| <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/to-be-cancel-failed.png">
|
| User popover after cancel (cancelled state) | <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/as-is-panel-after-cancel.png">
| <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/to-be-panel-after-cancel.png">
|
| Cancel request recorded | <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/as-is-network.png">
| <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/to-be-network.png">
|
| Settings billing panel | <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/as-is-billing-panel.png">
| <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/to-be-billing-panel.png">
|
| Resubscribe (Resume Pro) | <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/as-is-resubscribe.png">
| <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/to-be-resubscribe.png">
|
| Resubscribe request recorded | <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/as-is-resubscribe-network.png">
| <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/to-be-resubscribe-network.png">
|
| Payment-portal request recorded | <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/as-is-portal-network.png">
| <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/to-be-portal-network.png">
|

- AS-IS (flag off): cancel / resubscribe / portal POST the workspace API
directly; settlement and telemetry come from the legacy poller.
- TO-BE (flag on): the same dialogs and toasts, the POSTs go through the
SDK transport (`Idempotency-Key` on the request), settlement through the
operation lifecycle; a 404 falls back to the legacy call.

| Gate | Result |
| --- | --- |
| `vitest run src/platform/workspace/billing src/composables/billing
src/platform/workspace/composables src/platform/workspace/stores
src/composables/useFeatureFlags` | 41 files, 1138 tests (12 new
projection tests, 13 new adapter rail tests, +5 store tests) |
| `pnpm typecheck`, `pnpm typecheck:browser`, `lint`, `format:check`,
`knip` | exit 0 |
| `fallow audit --changed-since
origin/jaewon/fe-2210-hosted-destination-port` | no issues in 11 changed
files, complexity 0, duplication 0 |
| Playwright
`browser_tests/tests/dialogs/cancelSubscriptionSdkRail.spec.ts` (cloud
project) | **3 passed** against a served cloud dev build —
`PLAYWRIGHT_TEST_URL=http://localhost:5173 pnpm exec playwright test
--project=cloud
browser_tests/tests/dialogs/cancelSubscriptionSdkRail.spec.ts
--reporter=list`. Flag off → legacy request, flow unchanged; flag on →
SDK request (`Idempotency-Key`), same dialog outcome; flag on + 404 →
legacy fallback. |

Billing SDK track FE-2210 ([implementation plan
V2](https://app.notion.com/p/3d86d73d36508152b92cdbdfdfe83ac8)). Hybrid
model: top-up in-app, subscription management / invoices / payment
methods on the hosted billing app.

| Phase | Item | Ticket | Status |
| --- | --- | --- | --- |
| 1-2 | Session core, transport, readers | FE-2211/2212/2213 | merged |
| 3 | Operation lifecycle, commands, eight-state projection |
FE-2227/2214/2223 | merged (#17655) |
| 4 | `@comfyorg/account-ui` composables + `CheckoutSteps` | FE-2215 |
merged (#17662, #17663) |
| 5 slice 1 | Top-up through the SDK behind `billing_sdk_topup_enabled`
| FE-2216 | merged (#17665) |
| rollout C | `hosted_billing_destination` server flag read by the host
| FE-2218 | merged (#17716) |
| rollout C | `hostedDestination` port on the lifecycle, value on
operation state | FE-2210/2218 | #17783 (review; parent of this PR) |
| 7 prep | Scope-source port + credentialed transport (BFF / cookie
hosts) | FE-2218 | merged (#17782) |
| 7 prep | `@comfyorg/account` → `@comfyorg/account-core` rename |
FE-2218 | #17851 (review) |
| 7 prep | `billing-contract` route builder + `return_to` registry |
FE-2218 | merged (#17795) |
| 3A-3 | Workshop adapter over `createHostedTopupCheckout` | FE-2214 |
merged (#17793) |
| 8 core | `previewSubscribe` command | FE-2331 | merged (#17797) |
| 8 core | Plans + saved payment-methods readers | FE-2331 | #17798
(queued) |
| 8 ui | account-ui composables (`usePlans`, `usePaymentMethods`,
`usePreviewSubscribe`) | FE-2331 | #17798 (queued) |
| 7 | billing-web own-origin session, sign-in, SDK composition | FE-2218
| #17798 (queued) |
| 7 | billing-web unit tests in CI (`ci-billing-web-unit.yaml`) |
FE-2218 | merged (#17827); #17844 (queued) |
| 7 | ingest CORS + top-up return hosts for billing.comfy.org and its
previews (Comfy-Org/cloud) | FE-2218 | merged (Comfy-Org/cloud#9512) |
| 8 ui | billing-web `/v1` entry routing + subscription / payment-method
surfaces | FE-2331 | #17798 (queued) |
| 7 | npm publish (`ingest-types`, `account-core`, `billing-contract`),
Platform install, billing-web live top-up | FE-2218 | todo |
| 6 | Contract tests per generated schema (package layer) | FE-2217 |
| 6 | Live E2E per flow × consumer + evidence table | FE-2217 | todo
(needs staging flags) |
| 5 slice 2a | Cancel, resubscribe and payment portal through the SDK
behind `billing_sdk_subscription_enabled` | FE-2216 | **this PR** |
| 5 slice 2b | Subscribe / plan change through the SDK
(`previewSubscribe` quote, then subscribe; the SDK stops
short-circuiting an active plan) | FE-2216 | next, stacked on this PR |
| follow-up | One `needsCustomerAttention` predicate (from the #17665
review) | FE-2216 | merged (#17792) |
| follow-up | Opaque `BillingServerCode` (from the #17656 review) |
FE-2227 | merged (#17794) |
| follow-up | `useCredits` clears on `SUPERSEDED` (from the #17799
review) | FE-2215 | merged (#17824) |
| follow-up | credits / status / capabilities readers fence a late
failure as `SUPERSEDED` (from the #17798 review) | FE-2331 | merged
(#17828) |

```mermaid
flowchart LR
  P3["Phase 3 core lifecycle (merged)"]
  P4["Phase 4 account-ui (merged)"]
  P5["Phase 5 slice 1 top-up flag (merged)"]
  FC["PR 17716 hosted_billing_destination flag (merged)"]
  HD["PR 17783 hostedDestination port"]
  SS["PR 17782 scope-source port + credentialed transport"]
  RN["account-core rename"]
  RB["billing-contract route builder + return_to"]
  WS["Workshop adapter"]
  P8PV["previewSubscribe command"]
  P8RD["plans + payment-methods readers"]
  P8["account-ui hosted composables"]
  BWS["billing-web session + sign-in"]
  BWV["billing-web /v1 surfaces"]
  CORS["cloud PR 9512 ingest CORS + return hosts"]
  PUB["npm publish account-core / billing-contract"]
  P7["Phase 7 host proof: Platform + billing-web live"]
  P6C["Phase 6 contract tests"]
  P6["Phase 6 live evidence"]
  S2A["Phase 5 slice 2a cancel / resubscribe / portal rail"]
  S2B["Phase 5 slice 2b subscribe + plan change"]
  FU9["customer-attention predicate"]
  FU11["opaque BillingServerCode"]
  FU12["useCredits clears on SUPERSEDED"]
  FU13["reader late-failure fence"]
  P3 --> HD
  FC --> HD
  HD --> RB
  P3 --> SS
  SS --> P7
  RB --> P7
  P3 --> RN
  RN --> PUB
  RB --> PUB
  PUB --> P7
  P3 --> P8PV
  P3 --> P8RD
  P8PV --> P8
  P8RD --> P8
  P4 --> P8
  P8 --> S2B
  HD --> S2A
  S2A --> S2B
  P8 --> BWS
  BWS --> BWV
  RB --> BWV
  BWV --> P7
  CORS --> P7
  P5 --> P6
  P3 --> P6C
  P5 --> WS
  P5 --> FU9
  P3 --> FU11
  P4 --> FU12
  P3 --> FU13
  style P3 fill:#d4edda,stroke:#155724
  style P4 fill:#d4edda,stroke:#155724
  style P5 fill:#d4edda,stroke:#155724
  style FC fill:#d4edda,stroke:#155724
  style SS fill:#d4edda,stroke:#155724
  style RB fill:#d4edda,stroke:#155724
  style WS fill:#d4edda,stroke:#155724
  style FU9 fill:#d4edda,stroke:#155724
  style FU11 fill:#d4edda,stroke:#155724
  style FU12 fill:#d4edda,stroke:#155724
  style FU13 fill:#d4edda,stroke:#155724
  style CORS fill:#d4edda,stroke:#155724
  style P8PV fill:#d4edda,stroke:#155724
  style S2A stroke:#0366d6,stroke-width:4px
```
dante01yoon added a commit that referenced this pull request Sep 17, 2026
…the SDK rail behind billing_sdk_subscription_enabled (#17853)

Stacked on #17783 (base branch
`jaewon/fe-2210-hosted-destination-port`); merge that first.

Phase 5 slice 1 (#17665) moved top-up onto the Billing SDK behind
`billing_sdk_topup_enabled`. The subscription actions the host already
owns — cancel, resubscribe, and opening the payment portal — still call
the workspace API directly and rely on the legacy poller for settlement
and telemetry. This slice moves those three onto the SDK's commands
behind their own server flag, `billing_sdk_subscription_enabled`
(already on `/api/features` via Comfy-Org/cloud#9248, PostHog at 0%), so
the eight-state lifecycle, idempotency, recovery and telemetry come from
one implementation. Subscribe and plan change are slice 2b, stacked on
this PR.

- **Rail switch.** `billingSdkSubscriptionRailEnabled` =
`billing_sdk_subscription_enabled` AND `unified_cloud_auth`, exactly
like the top-up rail. `useSubscriptionRail()` reads it once,
synchronously, at the start of an action, so a flag flip mid-flow cannot
issue on one rail and observe on the other.
- **Three actions, one adapter.**
`useWorkspaceBilling.cancelSubscription / resubscribe /
manageSubscription` try the rail first; the store runs
`sdk.commands.cancelSubscription()`, `resubscribe()`,
`openPaymentPortal({ returnUrl })` and projects the result onto what the
adapter already does with the legacy calls: settle, or throw a
`WorkspaceApiError` (message is the host's, since the SDK never carries
server text; `serverCode` lands in `.code`). A command that settles in
any phase but `succeeded` is a failure, matching the poller. The refresh
after success mirrors the poller's: cancel → status + balance +
capabilities; resubscribe → `reconcileSubscriptionSuccess` +
capabilities.
- **Fallback.** A 404 (backend gate closed while the client flag is on)
projects to `unavailable`: the adapter runs its legacy body for that
action, and the store latches the route as unavailable for the tab so
later actions go straight to legacy without another failed round trip.
Every other failure — including `SUPERSEDED` — is thrown, never retried
on legacy, so a late or superseded result cannot double-issue.
- **Telemetry.** Lifecycle events are now reported for non-topup
operations (top-up keeps its resumed-only filter because its dialog
reports). `toBillingTelemetryEvent` already emits the poller's payload
shape, so dashboards cannot tell the rails apart.
- **No client-derived server state.** Eligibility and already-held
answers come from the SDK and the server, as for top-up. `subscribe`,
`previewSubscribe`, `useSubscriptionCheckout` and `useLegacyBilling` are
untouched.

| State | AS-IS (flag off) | TO-BE (flag on) |
| --- | --- | --- |
| Cancel dialog at rest | <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/as-is-cancel-dialog.png">
| <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/to-be-cancel-dialog.png">
|
| Cancel in flight | <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/as-is-cancel-in-flight.png">
| <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/to-be-cancel-in-flight.png">
|
| Cancel settled (success toast) | <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/as-is-cancel-settled.png">
| <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/to-be-cancel-settled.png">
|
| Cancel failed (error toast) | <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/as-is-cancel-failed.png">
| <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/to-be-cancel-failed.png">
|
| User popover after cancel (cancelled state) | <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/as-is-panel-after-cancel.png">
| <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/to-be-panel-after-cancel.png">
|
| Cancel request recorded | <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/as-is-network.png">
| <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/to-be-network.png">
|
| Settings billing panel | <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/as-is-billing-panel.png">
| <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/to-be-billing-panel.png">
|
| Resubscribe (Resume Pro) | <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/as-is-resubscribe.png">
| <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/to-be-resubscribe.png">
|
| Resubscribe request recorded | <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/as-is-resubscribe-network.png">
| <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/to-be-resubscribe-network.png">
|
| Payment-portal request recorded | <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/as-is-portal-network.png">
| <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17853-screenshots/screenshots/to-be-portal-network.png">
|

- AS-IS (flag off): cancel / resubscribe / portal POST the workspace API
directly; settlement and telemetry come from the legacy poller.
- TO-BE (flag on): the same dialogs and toasts, the POSTs go through the
SDK transport (`Idempotency-Key` on the request), settlement through the
operation lifecycle; a 404 falls back to the legacy call.

| Gate | Result |
| --- | --- |
| `vitest run src/platform/workspace/billing src/composables/billing
src/platform/workspace/composables src/platform/workspace/stores
src/composables/useFeatureFlags` | 41 files, 1138 tests (12 new
projection tests, 13 new adapter rail tests, +5 store tests) |
| `pnpm typecheck`, `pnpm typecheck:browser`, `lint`, `format:check`,
`knip` | exit 0 |
| `fallow audit --changed-since
origin/jaewon/fe-2210-hosted-destination-port` | no issues in 11 changed
files, complexity 0, duplication 0 |
| Playwright
`browser_tests/tests/dialogs/cancelSubscriptionSdkRail.spec.ts` (cloud
project) | **3 passed** against a served cloud dev build —
`PLAYWRIGHT_TEST_URL=http://localhost:5173 pnpm exec playwright test
--project=cloud
browser_tests/tests/dialogs/cancelSubscriptionSdkRail.spec.ts
--reporter=list`. Flag off → legacy request, flow unchanged; flag on →
SDK request (`Idempotency-Key`), same dialog outcome; flag on + 404 →
legacy fallback. |

Billing SDK track FE-2210 ([implementation plan
V2](https://app.notion.com/p/3d86d73d36508152b92cdbdfdfe83ac8)). Hybrid
model: top-up in-app, subscription management / invoices / payment
methods on the hosted billing app.

| Phase | Item | Ticket | Status |
| --- | --- | --- | --- |
| 1-2 | Session core, transport, readers | FE-2211/2212/2213 | merged |
| 3 | Operation lifecycle, commands, eight-state projection |
FE-2227/2214/2223 | merged (#17655) |
| 4 | `@comfyorg/account-ui` composables + `CheckoutSteps` | FE-2215 |
merged (#17662, #17663) |
| 5 slice 1 | Top-up through the SDK behind `billing_sdk_topup_enabled`
| FE-2216 | merged (#17665) |
| rollout C | `hosted_billing_destination` server flag read by the host
| FE-2218 | merged (#17716) |
| rollout C | `hostedDestination` port on the lifecycle, value on
operation state | FE-2210/2218 | #17783 (review; parent of this PR) |
| 7 prep | Scope-source port + credentialed transport (BFF / cookie
hosts) | FE-2218 | merged (#17782) |
| 7 prep | `@comfyorg/account` → `@comfyorg/account-core` rename |
FE-2218 | #17851 (review) |
| 7 prep | `billing-contract` route builder + `return_to` registry |
FE-2218 | merged (#17795) |
| 3A-3 | Workshop adapter over `createHostedTopupCheckout` | FE-2214 |
merged (#17793) |
| 8 core | `previewSubscribe` command | FE-2331 | merged (#17797) |
| 8 core | Plans + saved payment-methods readers | FE-2331 | #17798
(queued) |
| 8 ui | account-ui composables (`usePlans`, `usePaymentMethods`,
`usePreviewSubscribe`) | FE-2331 | #17798 (queued) |
| 7 | billing-web own-origin session, sign-in, SDK composition | FE-2218
| #17798 (queued) |
| 7 | billing-web unit tests in CI (`ci-billing-web-unit.yaml`) |
FE-2218 | merged (#17827); #17844 (queued) |
| 7 | ingest CORS + top-up return hosts for billing.comfy.org and its
previews (Comfy-Org/cloud) | FE-2218 | merged (Comfy-Org/cloud#9512) |
| 8 ui | billing-web `/v1` entry routing + subscription / payment-method
surfaces | FE-2331 | #17798 (queued) |
| 7 | npm publish (`ingest-types`, `account-core`, `billing-contract`),
Platform install, billing-web live top-up | FE-2218 | todo |
| 6 | Contract tests per generated schema (package layer) | FE-2217 |
| 6 | Live E2E per flow × consumer + evidence table | FE-2217 | todo
(needs staging flags) |
| 5 slice 2a | Cancel, resubscribe and payment portal through the SDK
behind `billing_sdk_subscription_enabled` | FE-2216 | **this PR** |
| 5 slice 2b | Subscribe / plan change through the SDK
(`previewSubscribe` quote, then subscribe; the SDK stops
short-circuiting an active plan) | FE-2216 | next, stacked on this PR |
| follow-up | One `needsCustomerAttention` predicate (from the #17665
review) | FE-2216 | merged (#17792) |
| follow-up | Opaque `BillingServerCode` (from the #17656 review) |
FE-2227 | merged (#17794) |
| follow-up | `useCredits` clears on `SUPERSEDED` (from the #17799
review) | FE-2215 | merged (#17824) |
| follow-up | credits / status / capabilities readers fence a late
failure as `SUPERSEDED` (from the #17798 review) | FE-2331 | merged
(#17828) |

```mermaid
flowchart LR
  P3["Phase 3 core lifecycle (merged)"]
  P4["Phase 4 account-ui (merged)"]
  P5["Phase 5 slice 1 top-up flag (merged)"]
  FC["PR 17716 hosted_billing_destination flag (merged)"]
  HD["PR 17783 hostedDestination port"]
  SS["PR 17782 scope-source port + credentialed transport"]
  RN["account-core rename"]
  RB["billing-contract route builder + return_to"]
  WS["Workshop adapter"]
  P8PV["previewSubscribe command"]
  P8RD["plans + payment-methods readers"]
  P8["account-ui hosted composables"]
  BWS["billing-web session + sign-in"]
  BWV["billing-web /v1 surfaces"]
  CORS["cloud PR 9512 ingest CORS + return hosts"]
  PUB["npm publish account-core / billing-contract"]
  P7["Phase 7 host proof: Platform + billing-web live"]
  P6C["Phase 6 contract tests"]
  P6["Phase 6 live evidence"]
  S2A["Phase 5 slice 2a cancel / resubscribe / portal rail"]
  S2B["Phase 5 slice 2b subscribe + plan change"]
  FU9["customer-attention predicate"]
  FU11["opaque BillingServerCode"]
  FU12["useCredits clears on SUPERSEDED"]
  FU13["reader late-failure fence"]
  P3 --> HD
  FC --> HD
  HD --> RB
  P3 --> SS
  SS --> P7
  RB --> P7
  P3 --> RN
  RN --> PUB
  RB --> PUB
  PUB --> P7
  P3 --> P8PV
  P3 --> P8RD
  P8PV --> P8
  P8RD --> P8
  P4 --> P8
  P8 --> S2B
  HD --> S2A
  S2A --> S2B
  P8 --> BWS
  BWS --> BWV
  RB --> BWV
  BWV --> P7
  CORS --> P7
  P5 --> P6
  P3 --> P6C
  P5 --> WS
  P5 --> FU9
  P3 --> FU11
  P4 --> FU12
  P3 --> FU13
  style P3 fill:#d4edda,stroke:#155724
  style P4 fill:#d4edda,stroke:#155724
  style P5 fill:#d4edda,stroke:#155724
  style FC fill:#d4edda,stroke:#155724
  style SS fill:#d4edda,stroke:#155724
  style RB fill:#d4edda,stroke:#155724
  style WS fill:#d4edda,stroke:#155724
  style FU9 fill:#d4edda,stroke:#155724
  style FU11 fill:#d4edda,stroke:#155724
  style FU12 fill:#d4edda,stroke:#155724
  style FU13 fill:#d4edda,stroke:#155724
  style CORS fill:#d4edda,stroke:#155724
  style P8PV fill:#d4edda,stroke:#155724
  style S2A stroke:#0366d6,stroke-width:4px
```
pull Bot pushed a commit to Penguinjanator/ComfyUI_frontend that referenced this pull request Sep 17, 2026
…unt-core (Comfy-Org#17851)

Stacked on Comfy-Org#17798 (base branch
`jaewon/fe-2331-plans-payment-methods-readers`); merge that first, then
this rebases to `main` with no content change.

## Why

Phase 7 (FE-2218) publishes the framework-free billing core to npm so
Platform can install it from a clean non-workspace checkout, and the
plan fixes the physical `account-core` / `account-ui` split as the
boundary that gets published, not the transitional `packages/account`.
The view package `@comfyorg/account-ui` already exists; the core still
carries the old name. This is the one mechanical rename PR the plan
schedules after Phase 5 slice 1 and before the first publish.

## How

Two commits so the review is trivial:

1. `git mv packages/account packages/account-core` — 95 files, 0
insertions, 0 deletions, every path a 100% rename.
2. The specifier and config edits — package name `@comfyorg/account` →
`@comfyorg/account-core`, every `workspace:*` dependency (root,
`apps/billing-web`, `apps/website`, `packages/account-ui`), every import
specifier under `src/`, `packages/`, `apps/`, `browser_tests/`, the root
`typecheck` / `lint` scripts (`typecheck:account` →
`typecheck:account-core`), `knip.config.ts`, `eslint.config.ts`, the
per-package loop and codecov file list in `ci-tests-unit.yaml`, the
lockfile importer keys, and the two ADRs that name the package in prose.
The delta over a 1:1 swap is oxfmt reflowing import lines the five extra
characters pushed past 80 columns.

Left alone on purpose: the `./vue` entry (the auth Vue pieces move to
`account-ui` in the next PR of this stack), the Firebase app name
`comfy-account` in ADR-0028, and the ADR filenames and headings
(renaming those would break the ADR index and inbound links). `git grep
"@comfyorg/account\b"` and `git grep "packages/account/"` return nothing
after this change.

The replay script lives under `temp/scripts/rename-account-core.sh`
(gitignored); if a sibling PR merges first, re-running it on a fresh
base reproduces this diff.

## AS-IS / TO-BE

No user-facing change; package boundary only.

- AS-IS: `packages/account` publishes as `@comfyorg/account` and is the
name Platform would have to install, while the view layer is already
`@comfyorg/account-ui`.
- TO-BE: `packages/account-core` publishes as `@comfyorg/account-core`;
`account-ui` and `billing-web` depend on it by the final name.

## Testing

| Gate | Result |
| --- | --- |
| `pnpm install --frozen-lockfile` | resolves with the new name |
| `packages/account-core` vitest | 41 files, 674 tests |
| `packages/account-ui` vitest | 9 files, 41 tests |
| `@comfyorg/billing-web` test:unit / build | 10 files, 90 tests / built
|
| `@comfyorg/website` typecheck | 0 errors |
| root `pnpm typecheck`, `lint`, `format`, `knip` | all exit 0 |
| `vitest run src/platform/workspace/billing` | 5 files, 50 tests |
| `pnpm typecheck:browser`, `typecheck:website` (pre-commit) | green |

## Where this sits in the plan

Billing SDK track FE-2210 ([implementation plan
V2](https://app.notion.com/p/3d86d73d36508152b92cdbdfdfe83ac8)). Hybrid
model: top-up in-app, subscription management / invoices / payment
methods on the hosted billing app.

| Phase | Item | Ticket | Status |
| --- | --- | --- | --- |
| 1-2 | Session core, transport, readers | FE-2211/2212/2213 | merged |
| 3 | Operation lifecycle, commands, eight-state projection |
FE-2227/2214/2223 | merged (Comfy-Org#17655) |
| 4 | `@comfyorg/account-ui` composables + `CheckoutSteps` | FE-2215 |
merged (Comfy-Org#17662, Comfy-Org#17663) |
| 5 slice 1 | Top-up through the SDK behind `billing_sdk_topup_enabled`
| FE-2216 | merged (Comfy-Org#17665) |
| rollout C | `hosted_billing_destination` server flag read by the host
| FE-2218 | merged (Comfy-Org#17716) |
| rollout C | `hostedDestination` port on the lifecycle, value on
operation state | FE-2210/2218 | Comfy-Org#17783 (review) |
| 7 prep | Scope-source port + credentialed transport (BFF / cookie
hosts) | FE-2218 | merged (Comfy-Org#17782) |
| 7 prep | `@comfyorg/account` → `@comfyorg/account-core` rename |
FE-2218 | **this PR** |
| 7 prep | `billing-contract` route builder + `return_to` registry |
FE-2218 | merged (Comfy-Org#17795) |
| 3A-3 | Workshop adapter over `createHostedTopupCheckout` | FE-2214 |
merged (Comfy-Org#17793) |
| 8 core | `previewSubscribe` command | FE-2331 | merged (Comfy-Org#17797) |
| 8 core | Plans + saved payment-methods readers | FE-2331 | Comfy-Org#17798
(review) |
| 8 ui | account-ui composables (`usePlans`, `usePaymentMethods`,
`usePreviewSubscribe`) | FE-2331 | Comfy-Org#17798 (review) |
| 7 | billing-web own-origin session, sign-in, SDK composition | FE-2218
| Comfy-Org#17798 (review) |
| 7 | billing-web unit tests in CI (`ci-billing-web-unit.yaml`) |
FE-2218 | merged (Comfy-Org#17827); Comfy-Org#17844 follow-up (review) |
| 7 | ingest CORS + top-up return hosts for billing.comfy.org and its
previews (Comfy-Org/cloud) | FE-2218 | merged (Comfy-Org/cloud#9512) |
| 8 ui | billing-web `/v1` entry routing + subscription / payment-method
surfaces | FE-2331 | Comfy-Org#17798 (review) |
| 7 | npm publish (`ingest-types`, `account-core`, `billing-contract`),
Platform install, billing-web live top-up | FE-2218 | todo |
| 6 | Contract tests per generated schema (package layer) | FE-2217 |
Comfy-Org#17829 (review) |
| 6 | Live E2E per flow × consumer + evidence table | FE-2217 | todo
(needs staging flags) |
| 5 slice 2 | Subscription flows through the SDK | FE-2216 | todo
(plan-change decision) |
| follow-up | One `needsCustomerAttention` predicate (from the Comfy-Org#17665
review) | FE-2216 | merged (Comfy-Org#17792) |
| follow-up | Opaque `BillingServerCode` (from the Comfy-Org#17656 review) |
FE-2227 | merged (Comfy-Org#17794) |
| follow-up | `useCredits` clears on `SUPERSEDED` (from the Comfy-Org#17799
review) | FE-2215 | merged (Comfy-Org#17824) |
| follow-up | credits / status / capabilities readers fence a late
failure as `SUPERSEDED` (from the Comfy-Org#17798 review) | FE-2331 | merged
(Comfy-Org#17828) |

```mermaid
flowchart LR
  P3["Phase 3 core lifecycle (merged)"]
  P4["Phase 4 account-ui (merged)"]
  P5["Phase 5 slice 1 top-up flag (merged)"]
  FC["PR 17716 hosted_billing_destination flag (merged)"]
  HD["PR 17783 hostedDestination port"]
  SS["PR 17782 scope-source port + credentialed transport"]
  RN["account-core rename"]
  RB["billing-contract route builder + return_to"]
  WS["Workshop adapter"]
  P8PV["previewSubscribe command"]
  P8RD["plans + payment-methods readers"]
  P8["account-ui hosted composables"]
  BWS["billing-web session + sign-in"]
  BWV["billing-web /v1 surfaces"]
  CORS["cloud PR 9512 ingest CORS + return hosts"]
  PUB["npm publish account-core / billing-contract"]
  P7["Phase 7 host proof: Platform + billing-web live"]
  P6C["Phase 6 contract tests"]
  P6["Phase 6 live evidence"]
  S2["Phase 5 slice 2 subscription"]
  FU9["customer-attention predicate"]
  FU11["opaque BillingServerCode"]
  FU12["useCredits clears on SUPERSEDED"]
  FU13["reader late-failure fence"]
  P3 --> HD
  FC --> HD
  HD --> RB
  P3 --> SS
  SS --> P7
  RB --> P7
  P3 --> RN
  RN --> PUB
  RB --> PUB
  PUB --> P7
  P3 --> P8PV
  P3 --> P8RD
  P8PV --> P8
  P8RD --> P8
  P4 --> P8
  P8 --> S2
  P8 --> BWS
  BWS --> BWV
  RB --> BWV
  BWV --> P7
  CORS --> P7
  P5 --> P6
  P3 --> P6C
  P5 --> WS
  P5 --> FU9
  P3 --> FU11
  P4 --> FU12
  P3 --> FU13
  style P3 fill:#d4edda,stroke:#155724
  style P4 fill:#d4edda,stroke:#155724
  style P5 fill:#d4edda,stroke:#155724
  style FC fill:#d4edda,stroke:#155724
  style SS fill:#d4edda,stroke:#155724
  style RB fill:#d4edda,stroke:#155724
  style WS fill:#d4edda,stroke:#155724
  style FU9 fill:#d4edda,stroke:#155724
  style FU11 fill:#d4edda,stroke:#155724
  style FU12 fill:#d4edda,stroke:#155724
  style FU13 fill:#d4edda,stroke:#155724
  style CORS fill:#d4edda,stroke:#155724
  style P8PV fill:#d4edda,stroke:#155724
  style RN stroke:#0366d6,stroke-width:4px
```
pull Bot pushed a commit to Mu-L/ComfyUI_frontend that referenced this pull request Sep 17, 2026
…ling core (Comfy-Org#17854)

Stacked on Comfy-Org#17851 (base branch `jaewon/fe-2218-account-core-rename`),
which stacks on Comfy-Org#17798; merge those first.

## Why

The plan's first decision was that the Vue layer leaves the account
package: composables and unstyled components ship from
`@comfyorg/account-ui`, and the core keeps zero Vue coupling by
construction rather than by an import-guard test. The auth Vue pieces
(`PasswordRules`, `SocialAuthButtons`, `TurnstileWidget`, the region and
Turnstile gates, the lifecycle scope and generation guard) had shipped
in the core's `./vue` entry days before that decision and were
deliberately left for a later follow-up so the fresh auth stack was not
destabilised. With the rename in Comfy-Org#17851 fixing `account-core` as the
boundary that gets published (Phase 7), this is that follow-up: the
published core must not drag `vue`, `@vueuse/core` or a `.vue` entry to
Platform.

## How

- `packages/account-core/src/vue/**` → `packages/account-ui/src/auth/**`
with `git mv` (7 modules + their 7 tests; git records every file as a
rename). The framework-free helpers stay in the core and keep their
public subpaths (`/signInSchemas`, `/turnstileScript`,
`/boundedOperation`); the moved files reach them through those.
- `@comfyorg/account-ui` gains per-module `./auth/*` exports (mirroring
how consumers already import these individually and how the app-side
test mocks target one module each) plus the two workspace deps the moved
files need (`@comfyorg/shared-frontend-utils`,
`@comfyorg/tailwind-utils`; both fine in the view package, neither
allowed in the core).
- The core drops the `./vue/*` exports, `vue`, `@vueuse/core`,
`vue-tsc`, `@vitejs/plugin-vue`, `@testing-library/vue|user-event`,
`@comfyorg/tailwind-utils` and the `peerDependenciesMeta` block;
`typecheck` becomes `tsc --noEmit`; the vitest `account-vue` project
becomes `account-firebase` (happy-dom for `src/firebase/**` only).
- `vueBoundary.test.ts` now proves the boundary three ways: no `vue` /
`@vueuse` import anywhere under `src` (the old `vue/` carve-out is
gone), no Vue dependency in any manifest field, and no `.vue` file
behind any export.
- 17 import sites in 13 files repointed (`apps/billing-web`,
`apps/website`, `src/`); root and `apps/website` gain
`@comfyorg/account-ui: workspace:*`.

A pure `git mv` commit was not possible: the pre-commit hook lints and
type-checks the staged tree, and a rename without repoints leaves 17
unresolved imports. Commit 1 is therefore the rename plus the mechanical
repoints; commit 2 is the boundary guard.

## AS-IS / TO-BE

No user-facing change; package boundary only.

- AS-IS: `@comfyorg/account-core` exports `./vue/*` and depends on
`vue`; a Platform install of the core would pull Vue and `.vue` files.
- TO-BE: `@comfyorg/account-core` has no view entry and no Vue
dependency; the sign-in pieces ship from `@comfyorg/account-ui/auth/*`
next to `./billing`.

## Testing

| Gate | Result |
| --- | --- |
| `packages/account-core` vitest | 34 files, 638 tests |
| `packages/account-ui` vitest | 16 files, 79 tests (7 moved suites) |
| `@comfyorg/billing-web` test:unit / build | 10 files, 90 tests / built
|
| `@comfyorg/website` typecheck | 0 errors |
| root `pnpm typecheck`, `lint`, `format`, `knip` | exit 0 |
| `vitest run src/components/dialog/content/signin src/components/auth
src/platform/workspace/billing` | 11 files, 94 tests |
| `git grep "account-core/vue"` | no matches |

## Where this sits in the plan

Billing SDK track FE-2210 ([implementation plan
V2](https://app.notion.com/p/3d86d73d36508152b92cdbdfdfe83ac8)). Hybrid
model: top-up in-app, subscription management / invoices / payment
methods on the hosted billing app.

| Phase | Item | Ticket | Status |
| --- | --- | --- | --- |
| 1-2 | Session core, transport, readers | FE-2211/2212/2213 | merged |
| 3 | Operation lifecycle, commands, eight-state projection |
FE-2227/2214/2223 | merged (Comfy-Org#17655) |
| 4 | `@comfyorg/account-ui` composables + `CheckoutSteps` | FE-2215 |
merged (Comfy-Org#17662, Comfy-Org#17663) |
| 5 slice 1 | Top-up through the SDK behind `billing_sdk_topup_enabled`
| FE-2216 | merged (Comfy-Org#17665) |
| rollout C | `hosted_billing_destination` server flag read by the host
| FE-2218 | merged (Comfy-Org#17716) |
| rollout C | `hostedDestination` port on the lifecycle, value on
operation state | FE-2210/2218 | Comfy-Org#17783 (review) |
| 7 prep | Scope-source port + credentialed transport (BFF / cookie
hosts) | FE-2218 | merged (Comfy-Org#17782) |
| 7 prep | `@comfyorg/account` → `@comfyorg/account-core` rename |
FE-2218 | Comfy-Org#17851 (review; parent of this PR) |
| 4 follow-up | auth Vue pieces leave the core for
`@comfyorg/account-ui` (`./auth/*`) | FE-2215 | **this PR** |
| 7 prep | `billing-contract` route builder + `return_to` registry |
FE-2218 | merged (Comfy-Org#17795) |
| 3A-3 | Workshop adapter over `createHostedTopupCheckout` | FE-2214 |
merged (Comfy-Org#17793) |
| 8 core | `previewSubscribe` command | FE-2331 | merged (Comfy-Org#17797) |
| 8 core | Plans + saved payment-methods readers | FE-2331 | Comfy-Org#17798
(queued) |
| 8 ui | account-ui composables (`usePlans`, `usePaymentMethods`,
`usePreviewSubscribe`) | FE-2331 | Comfy-Org#17798 (queued) |
| 7 | billing-web own-origin session, sign-in, SDK composition | FE-2218
| Comfy-Org#17798 (queued) |
| 7 | billing-web unit tests in CI (`ci-billing-web-unit.yaml`) |
FE-2218 | merged (Comfy-Org#17827); Comfy-Org#17844 (queued) |
| 7 | ingest CORS + top-up return hosts for billing.comfy.org and its
previews (Comfy-Org/cloud) | FE-2218 | merged (Comfy-Org/cloud#9512) |
| 8 ui | billing-web `/v1` entry routing + subscription / payment-method
surfaces | FE-2331 | Comfy-Org#17798 (queued) |
| 7 | npm publish (`ingest-types`, `account-core`, `billing-contract`),
Platform install, billing-web live top-up | FE-2218 | todo |
| 6 | Contract tests per generated schema (package layer) | FE-2217 |
Comfy-Org#17829 (review) |
| 6 | Live E2E per flow × consumer + evidence table | FE-2217 | todo
(needs staging flags) |
| 5 slice 2 | Subscription flows through the SDK | FE-2216 | todo
(plan-change decision) |
| follow-up | One `needsCustomerAttention` predicate (from the Comfy-Org#17665
review) | FE-2216 | merged (Comfy-Org#17792) |
| follow-up | Opaque `BillingServerCode` (from the Comfy-Org#17656 review) |
FE-2227 | merged (Comfy-Org#17794) |
| follow-up | `useCredits` clears on `SUPERSEDED` (from the Comfy-Org#17799
review) | FE-2215 | merged (Comfy-Org#17824) |
| follow-up | credits / status / capabilities readers fence a late
failure as `SUPERSEDED` (from the Comfy-Org#17798 review) | FE-2331 | merged
(Comfy-Org#17828) |

```mermaid
flowchart LR
  P3["Phase 3 core lifecycle (merged)"]
  P4["Phase 4 account-ui (merged)"]
  P5["Phase 5 slice 1 top-up flag (merged)"]
  FC["PR 17716 hosted_billing_destination flag (merged)"]
  HD["PR 17783 hostedDestination port"]
  SS["PR 17782 scope-source port + credentialed transport"]
  RN["PR 17851 account-core rename"]
  VUE["auth Vue pieces to account-ui"]
  RB["billing-contract route builder + return_to"]
  WS["Workshop adapter"]
  P8PV["previewSubscribe command"]
  P8RD["plans + payment-methods readers"]
  P8["account-ui hosted composables"]
  BWS["billing-web session + sign-in"]
  BWV["billing-web /v1 surfaces"]
  CORS["cloud PR 9512 ingest CORS + return hosts"]
  PUB["npm publish account-core / billing-contract"]
  P7["Phase 7 host proof: Platform + billing-web live"]
  P6C["Phase 6 contract tests"]
  P6["Phase 6 live evidence"]
  S2["Phase 5 slice 2 subscription"]
  FU9["customer-attention predicate"]
  FU11["opaque BillingServerCode"]
  FU12["useCredits clears on SUPERSEDED"]
  FU13["reader late-failure fence"]
  P3 --> HD
  FC --> HD
  HD --> RB
  P3 --> SS
  SS --> P7
  RB --> P7
  P3 --> RN
  RN --> PUB
  RN --> VUE
  RB --> PUB
  PUB --> P7
  P3 --> P8PV
  P3 --> P8RD
  P8PV --> P8
  P8RD --> P8
  P4 --> P8
  P8 --> S2
  P8 --> BWS
  BWS --> BWV
  RB --> BWV
  BWV --> P7
  CORS --> P7
  P5 --> P6
  P3 --> P6C
  P5 --> WS
  P5 --> FU9
  P3 --> FU11
  P4 --> FU12
  P3 --> FU13
  style P3 fill:#d4edda,stroke:#155724
  style P4 fill:#d4edda,stroke:#155724
  style P5 fill:#d4edda,stroke:#155724
  style FC fill:#d4edda,stroke:#155724
  style SS fill:#d4edda,stroke:#155724
  style RB fill:#d4edda,stroke:#155724
  style WS fill:#d4edda,stroke:#155724
  style FU9 fill:#d4edda,stroke:#155724
  style FU11 fill:#d4edda,stroke:#155724
  style FU12 fill:#d4edda,stroke:#155724
  style FU13 fill:#d4edda,stroke:#155724
  style CORS fill:#d4edda,stroke:#155724
  style P8PV fill:#d4edda,stroke:#155724
  style VUE stroke:#0366d6,stroke-width:4px
```
dante01yoon added a commit that referenced this pull request Sep 17, 2026
…act when the hosted destination says billing_web (#17860)

Stacked on #17856 (base branch `jaewon/fe-2216-plan-change`) → #17853 →
#17783; merge those first.

## Why

Rollout layer C (`hosted_billing_destination`, `stripe` | `billing_web`,
PostHog at 100% `stripe`) decides where a hosted billing action lands.
The plan says the host reads the flag, hands it to the SDK (#17783) and,
when it says `billing_web`, mints a `/v1/<intent>` entry with
`return_to` from `@comfyorg/billing-contract`, the one definition of
that route surface (#17795); when it says `stripe`, the backend's URL is
opened unchanged. Today the host only opens the bare billing-web origin
from the user popover (#17716) with no intent and no `return_to`, and
"Billing & invoices" in the settings panel always goes to the Stripe
portal. This is the last un-opened code item before the Phase 7 host
proof.

## How

- `src/platform/workspace/billing/hostedBillingRoutes.ts`:
`hostedBillingRoute(destination, intent)` returns `{ kind:
'billing_web', url }` built by `buildBillingEntryUrl({ billingOrigin,
intent, product: 'comfyui', returnTo: 'comfyui_workspace' })`, or `{
kind: 'provider' }` meaning "use the server's URL". The environment is
derived, not hardcoded: the cloud base URL's hostname through the
existing `resolveDeployEnv` map (`prod-v2 | stg-v2 | test-v2` →
`production | staging | test`), which also classifies a local dev
session by the backend it talks to. Fails closed to the provider on: no
configured origin, an unknown backend family, a return target with no
destination in that family, or an entry the contract refuses. A
path-prefixed `VITE_BILLING_WEB_URL` keeps its prefix under the minted
route.
- Consumers: the popover's "Plans and pricing" mints the `pricing`
intent (billing-web routes it to the subscription view; the in-app
dialog stays the `stripe` behaviour and the popup-blocked fallback);
`useWorkspaceBilling.manageSubscription()` mints `payment-methods`
**before** either rail is consulted, so on `billing_web` no portal URL
is requested on the SDK rail or the legacy one, and `openPortalWindow` +
`refreshOnPortalReturn` still run so the return re-reads status, balance
and capabilities.
- Also fixed on the way: the popover treated a falsy `window.open(…,
"noopener,noreferrer")` result as a blocked popup and showed the in-app
pricing dialog as a fallback. Per the HTML spec `noopener` always
returns `null`, so on `billing_web` the tab and the dialog opened
together — a latent defect inherited from #17370 on `main`, caught by
this PR's evidence run. The fallback is gone; the E2E `window.open` stub
now returns `null` for `noopener` like a browser does, and a popover
case covers both destinations.
- Left on the provider on purpose:
`useSubscriptionCheckout.recoverOutstandingPayment` and the
`payment_method_url` steps inside an operation are mid-checkout provider
steps, not hosted management; `invoices` and `result` are not served by
billing-web yet (`ComingSoonView`), so nothing mints them; the legacy
`/customers` rail's `accessBillingPortal` is being retired by the
personal-billing flip and is not touched.
- `@comfyorg/billing-contract` becomes a root `workspace:*` dependency.
The CI cloud build for E2E (`.github/actions/build-cloud-frontend`, used
only by `ci-tests-e2e.yaml` and
`pr-update-playwright-expectations.yaml`, never by a deploy) gets
`VITE_BILLING_WEB_URL=https://billing-web.example`, a reserved origin
the spec stubs, reachable only when the server flag says `billing_web`.
- No frontend-derived server state: the destination is the flag as-is;
the host chooses only the URL shape.

## AS-IS / TO-BE

| AS-IS — `hosted_billing_destination: stripe` | TO-BE —
`hosted_billing_destination: billing_web` |
| --- | --- |
| **1. User popover, "Plans and pricing" hovered**<br><img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17860-screenshots/screenshots/as-is-popover-plans.png"><br>Same
menu item, unchanged by the flag. | **1. User popover, "Plans and
pricing" hovered**<br><img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17860-screenshots/screenshots/to-be-popover-plans.png"><br>Same
menu item, unchanged by the flag. |
| **2. After clicking "Plans and pricing"**<br><img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17860-screenshots/screenshots/as-is-plans-result.png"><br>In-app
"Choose a Plan" dialog, no tab opened. | **2. After clicking "Plans and
pricing"**<br><img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17860-screenshots/screenshots/to-be-plans-result.png"><br>`billing-web.example/v1/pricing?product=comfyui&return_to=comfyui_workspace`
tab opens and nothing else: `window.open` returns `null` under
`noopener` as the spec requires, and no in-app dialog is left behind. |
| **3. Settings ▸ Workspace ▸ Plan & Credits, before clicking "Billing &
invoices"**<br><img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17860-screenshots/screenshots/as-is-settings-billing.png"><br>Identical
panel; the destination is only read on click. | **3. Settings ▸
Workspace ▸ Plan & Credits, before clicking "Billing &
invoices"**<br><img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17860-screenshots/screenshots/to-be-settings-billing.png"><br>Identical
panel; the destination is only read on click. |
| **4. After clicking "Billing & invoices"**<br><img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17860-screenshots/screenshots/as-is-manage-result.png"><br>`POST
/api/billing/payment-portal` recorded, and the URL it returned
(`https://billing.example/portal`) opened. | **4. After clicking
"Billing & invoices"**<br><img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17860-screenshots/screenshots/to-be-manage-result.png"><br>No
request to `/api/billing/payment-portal` on either rail;
`billing-web.example/v1/payment-methods?product=comfyui&return_to=comfyui_workspace`
minted and opened. |
| **5. Return trip — refocusing the app tab after the hosted tab
opened**<br><img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17860-screenshots/screenshots/as-is-return-refresh.png"><br>`/api/billing/status`,
`/balance` and `/capabilities` re-read. | **5. Return trip — refocusing
the app tab after the hosted tab opened**<br><img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17860-screenshots/screenshots/to-be-return-refresh.png"><br>Same
three reads; `openPortalWindow` + `refreshOnPortalReturn` still run on
the minted route. |

- AS-IS (`stripe`, today's default): popover → in-app pricing dialog;
settings → Stripe portal via `POST /billing/payment-portal`.
- TO-BE (`billing_web`): popover →
`<billing-web>/v1/pricing?product=comfyui&return_to=comfyui_workspace`;
settings → `<billing-web>/v1/payment-methods?…`, no portal request on
either rail; the app re-reads billing state on return.

## Testing

| Gate | Result |
| --- | --- |
| `vitest run src/platform/workspace src/composables/billing
src/composables/useFeatureFlags src/config` | 91 files, 1890 tests (19
new route cases: intent × destination × env × prefix × each fail-closed
branch; 3 new adapter cases; 3 popover cases re-pointed) |
| `packages/billing-contract` vitest | 3 files, 62 tests |
| `pnpm typecheck`, `typecheck:browser`, `lint`, `format`, `knip` | exit
0 |
| `fallow audit --changed-since origin/jaewon/fe-2216-plan-change` | no
issues in 10 changed files |
| `PLAYWRIGHT_TEST_URL=http://localhost:5431 pnpm exec playwright test
--project=cloud
browser_tests/tests/dialogs/hostedBillingDestination.spec.ts
--reporter=list`, against
`VITE_BILLING_WEB_URL=https://billing-web.example pnpm dev:cloud` | `4
passed (4.6s)` — settings on both destinations, plus the two new
avatar-menu cases: `opens the in-app pricing table from the avatar menu
while the destination is stripe` and `opens the billing-web pricing
entry alone from the avatar menu while the destination is billing_web` |

## Where this sits in the plan

Billing SDK track FE-2210 ([implementation plan
V2](https://app.notion.com/p/3d86d73d36508152b92cdbdfdfe83ac8)). Hybrid
model: top-up in-app, subscription management / invoices / payment
methods on the hosted billing app.

| Phase | Item | Ticket | Status |
| --- | --- | --- | --- |
| 1-2 | Session core, transport, readers | FE-2211/2212/2213 | merged |
| 3 | Operation lifecycle, commands, eight-state projection |
FE-2227/2214/2223 | merged (#17655) |
| 4 | `@comfyorg/account-ui` composables + `CheckoutSteps` | FE-2215 |
merged (#17662, #17663) |
| 5 slice 1 | Top-up through the SDK behind `billing_sdk_topup_enabled`
| FE-2216 | merged (#17665) |
| rollout C | `hosted_billing_destination` server flag read by the host
| FE-2218 | merged (#17716) |
| rollout C | `hostedDestination` port on the lifecycle, value on
operation state | FE-2210/2218 | #17783 (review) |
| 7 prep | Scope-source port + credentialed transport (BFF / cookie
hosts) | FE-2218 | merged (#17782) |
| 7 prep | `@comfyorg/account` → `@comfyorg/account-core` rename |
FE-2218 | #17851 (review) |
| 7 prep | `billing-contract` route builder + `return_to` registry |
FE-2218 | merged (#17795) |
| 3A-3 | Workshop adapter over `createHostedTopupCheckout` | FE-2214 |
merged (#17793) |
| 8 core | `previewSubscribe` command | FE-2331 | merged (#17797) |
| 8 core | Plans + saved payment-methods readers | FE-2331 | merged
(#17798) |
| 8 ui | account-ui composables (`usePlans`, `usePaymentMethods`,
`usePreviewSubscribe`) | FE-2331 | merged (#17798) |
| 7 | billing-web own-origin session, sign-in, SDK composition | FE-2218
| merged (#17798) |
| 7 | billing-web unit tests in CI (`ci-billing-web-unit.yaml`) |
FE-2218 | merged (#17827, #17844) |
| 7 | ingest CORS + top-up return hosts for billing.comfy.org and its
previews (Comfy-Org/cloud) | FE-2218 | merged (Comfy-Org/cloud#9512) |
| 8 ui | billing-web `/v1` entry routing + subscription / payment-method
surfaces | FE-2331 | merged (#17798) |
| 7 | npm publish (`ingest-types`, `account-core`, `billing-contract`),
Platform install, billing-web live top-up | FE-2218 | todo |
| 6 | Contract tests per generated schema (package layer) | FE-2217 |
#17829 (review) |
| 6 | Live E2E per flow × consumer + evidence table | FE-2217 | todo
(needs staging flags) |
| 5 slice 2a | Cancel, resubscribe and payment portal through the SDK
behind `billing_sdk_subscription_enabled` | FE-2216 | #17853 (review) |
| 5 slice 2b | Subscribe and plan change through the SDK, priced by the
server | FE-2216 | #17856 (review; parent of this PR) |
| 7 / rollout C | Host mints billing-web `/v1/<intent>` entries with
`return_to` when `hosted_billing_destination` is `billing_web` | FE-2218
| **this PR** |
| follow-up | One `needsCustomerAttention` predicate (from the #17665
review) | FE-2216 | merged (#17792) |
| follow-up | Opaque `BillingServerCode` (from the #17656 review) |
FE-2227 | merged (#17794) |
| follow-up | `useCredits` clears on `SUPERSEDED` (from the #17799
review) | FE-2215 | merged (#17824) |
| follow-up | credits / status / capabilities readers fence a late
failure as `SUPERSEDED` (from the #17798 review) | FE-2331 | merged
(#17828) |

```mermaid
flowchart LR
  P3["Phase 3 core lifecycle (merged)"]
  P4["Phase 4 account-ui (merged)"]
  P5["Phase 5 slice 1 top-up flag (merged)"]
  FC["PR 17716 hosted_billing_destination flag (merged)"]
  HD["PR 17783 hostedDestination port"]
  SS["PR 17782 scope-source port + credentialed transport"]
  RN["account-core rename"]
  RB["billing-contract route builder + return_to"]
  WS["Workshop adapter"]
  P8PV["previewSubscribe command"]
  P8RD["plans + payment-methods readers"]
  P8["account-ui hosted composables"]
  BWS["billing-web session + sign-in"]
  BWV["billing-web /v1 surfaces"]
  CORS["cloud PR 9512 ingest CORS + return hosts"]
  PUB["npm publish account-core / billing-contract"]
  P7["Phase 7 host proof: Platform + billing-web live"]
  P6C["Phase 6 contract tests"]
  P6["Phase 6 live evidence"]
  S2A["PR 17853 slice 2a cancel / resubscribe / portal rail"]
  S2B["PR 17856 slice 2b subscribe + plan change"]
  LC["Layer C: host mints billing-web entries"]
  FU9["customer-attention predicate"]
  FU11["opaque BillingServerCode"]
  FU12["useCredits clears on SUPERSEDED"]
  FU13["reader late-failure fence"]
  P3 --> HD
  FC --> HD
  HD --> RB
  P3 --> SS
  SS --> P7
  RB --> P7
  P3 --> RN
  RN --> PUB
  RB --> PUB
  PUB --> P7
  P3 --> P8PV
  P3 --> P8RD
  P8PV --> P8
  P8RD --> P8
  P4 --> P8
  P8 --> S2B
  HD --> S2A
  S2A --> S2B
  S2B --> LC
  RB --> LC
  HD --> LC
  LC --> P7
  P8 --> BWS
  BWS --> BWV
  RB --> BWV
  BWV --> P7
  CORS --> P7
  P5 --> P6
  P3 --> P6C
  P5 --> WS
  P5 --> FU9
  P3 --> FU11
  P4 --> FU12
  P3 --> FU13
  style P3 fill:#d4edda,stroke:#155724
  style P4 fill:#d4edda,stroke:#155724
  style P5 fill:#d4edda,stroke:#155724
  style FC fill:#d4edda,stroke:#155724
  style SS fill:#d4edda,stroke:#155724
  style RB fill:#d4edda,stroke:#155724
  style WS fill:#d4edda,stroke:#155724
  style FU9 fill:#d4edda,stroke:#155724
  style BWV fill:#d4edda,stroke:#155724
  style BWS fill:#d4edda,stroke:#155724
  style P8 fill:#d4edda,stroke:#155724
  style P8RD fill:#d4edda,stroke:#155724
  style CORS fill:#d4edda,stroke:#155724
  style FU13 fill:#d4edda,stroke:#155724
  style FU12 fill:#d4edda,stroke:#155724
  style FU11 fill:#d4edda,stroke:#155724
  style P8PV fill:#d4edda,stroke:#155724
  style LC stroke:#0366d6,stroke-width:4px
```
dante01yoon added a commit that referenced this pull request Sep 17, 2026
…act when the hosted destination says billing_web (#17860)

Stacked on #17856 (base branch `jaewon/fe-2216-plan-change`) → #17853 →

Rollout layer C (`hosted_billing_destination`, `stripe` | `billing_web`,
PostHog at 100% `stripe`) decides where a hosted billing action lands.
The plan says the host reads the flag, hands it to the SDK (#17783) and,
when it says `billing_web`, mints a `/v1/<intent>` entry with
`return_to` from `@comfyorg/billing-contract`, the one definition of
that route surface (#17795); when it says `stripe`, the backend's URL is
opened unchanged. Today the host only opens the bare billing-web origin
from the user popover (#17716) with no intent and no `return_to`, and
"Billing & invoices" in the settings panel always goes to the Stripe
portal. This is the last un-opened code item before the Phase 7 host
proof.

- `src/platform/workspace/billing/hostedBillingRoutes.ts`:
`hostedBillingRoute(destination, intent)` returns `{ kind:
'billing_web', url }` built by `buildBillingEntryUrl({ billingOrigin,
intent, product: 'comfyui', returnTo: 'comfyui_workspace' })`, or `{
kind: 'provider' }` meaning "use the server's URL". The environment is
derived, not hardcoded: the cloud base URL's hostname through the
existing `resolveDeployEnv` map (`prod-v2 | stg-v2 | test-v2` →
`production | staging | test`), which also classifies a local dev
session by the backend it talks to. Fails closed to the provider on: no
configured origin, an unknown backend family, a return target with no
destination in that family, or an entry the contract refuses. A
path-prefixed `VITE_BILLING_WEB_URL` keeps its prefix under the minted
route.
- Consumers: the popover's "Plans and pricing" mints the `pricing`
intent (billing-web routes it to the subscription view; the in-app
dialog stays the `stripe` behaviour and the popup-blocked fallback);
`useWorkspaceBilling.manageSubscription()` mints `payment-methods`
**before** either rail is consulted, so on `billing_web` no portal URL
is requested on the SDK rail or the legacy one, and `openPortalWindow` +
`refreshOnPortalReturn` still run so the return re-reads status, balance
and capabilities.
- Also fixed on the way: the popover treated a falsy `window.open(…,
"noopener,noreferrer")` result as a blocked popup and showed the in-app
pricing dialog as a fallback. Per the HTML spec `noopener` always
returns `null`, so on `billing_web` the tab and the dialog opened
together — a latent defect inherited from #17370 on `main`, caught by
this PR's evidence run. The fallback is gone; the E2E `window.open` stub
now returns `null` for `noopener` like a browser does, and a popover
case covers both destinations.
- Left on the provider on purpose:
`useSubscriptionCheckout.recoverOutstandingPayment` and the
`payment_method_url` steps inside an operation are mid-checkout provider
steps, not hosted management; `invoices` and `result` are not served by
billing-web yet (`ComingSoonView`), so nothing mints them; the legacy
`/customers` rail's `accessBillingPortal` is being retired by the
personal-billing flip and is not touched.
- `@comfyorg/billing-contract` becomes a root `workspace:*` dependency.
The CI cloud build for E2E (`.github/actions/build-cloud-frontend`, used
only by `ci-tests-e2e.yaml` and
`pr-update-playwright-expectations.yaml`, never by a deploy) gets
`VITE_BILLING_WEB_URL=https://billing-web.example`, a reserved origin
the spec stubs, reachable only when the server flag says `billing_web`.
- No frontend-derived server state: the destination is the flag as-is;
the host chooses only the URL shape.

| AS-IS — `hosted_billing_destination: stripe` | TO-BE —
`hosted_billing_destination: billing_web` |
| --- | --- |
| **1. User popover, "Plans and pricing" hovered**<br><img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17860-screenshots/screenshots/as-is-popover-plans.png"><br>Same
menu item, unchanged by the flag. | **1. User popover, "Plans and
pricing" hovered**<br><img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17860-screenshots/screenshots/to-be-popover-plans.png"><br>Same
menu item, unchanged by the flag. |
| **2. After clicking "Plans and pricing"**<br><img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17860-screenshots/screenshots/as-is-plans-result.png"><br>In-app
"Choose a Plan" dialog, no tab opened. | **2. After clicking "Plans and
pricing"**<br><img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17860-screenshots/screenshots/to-be-plans-result.png"><br>`billing-web.example/v1/pricing?product=comfyui&return_to=comfyui_workspace`
tab opens and nothing else: `window.open` returns `null` under
`noopener` as the spec requires, and no in-app dialog is left behind. |
| **3. Settings ▸ Workspace ▸ Plan & Credits, before clicking "Billing &
invoices"**<br><img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17860-screenshots/screenshots/as-is-settings-billing.png"><br>Identical
panel; the destination is only read on click. | **3. Settings ▸
Workspace ▸ Plan & Credits, before clicking "Billing &
invoices"**<br><img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17860-screenshots/screenshots/to-be-settings-billing.png"><br>Identical
panel; the destination is only read on click. |
| **4. After clicking "Billing & invoices"**<br><img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17860-screenshots/screenshots/as-is-manage-result.png"><br>`POST
/api/billing/payment-portal` recorded, and the URL it returned
(`https://billing.example/portal`) opened. | **4. After clicking
"Billing & invoices"**<br><img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17860-screenshots/screenshots/to-be-manage-result.png"><br>No
request to `/api/billing/payment-portal` on either rail;
`billing-web.example/v1/payment-methods?product=comfyui&return_to=comfyui_workspace`
minted and opened. |
| **5. Return trip — refocusing the app tab after the hosted tab
opened**<br><img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17860-screenshots/screenshots/as-is-return-refresh.png"><br>`/api/billing/status`,
`/balance` and `/capabilities` re-read. | **5. Return trip — refocusing
the app tab after the hosted tab opened**<br><img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17860-screenshots/screenshots/to-be-return-refresh.png"><br>Same
three reads; `openPortalWindow` + `refreshOnPortalReturn` still run on
the minted route. |

- AS-IS (`stripe`, today's default): popover → in-app pricing dialog;
settings → Stripe portal via `POST /billing/payment-portal`.
- TO-BE (`billing_web`): popover →
`<billing-web>/v1/pricing?product=comfyui&return_to=comfyui_workspace`;
settings → `<billing-web>/v1/payment-methods?…`, no portal request on
either rail; the app re-reads billing state on return.

| Gate | Result |
| --- | --- |
| `vitest run src/platform/workspace src/composables/billing
src/composables/useFeatureFlags src/config` | 91 files, 1890 tests (19
new route cases: intent × destination × env × prefix × each fail-closed
branch; 3 new adapter cases; 3 popover cases re-pointed) |
| `packages/billing-contract` vitest | 3 files, 62 tests |
| `pnpm typecheck`, `typecheck:browser`, `lint`, `format`, `knip` | exit
0 |
| `fallow audit --changed-since origin/jaewon/fe-2216-plan-change` | no
issues in 10 changed files |
| `PLAYWRIGHT_TEST_URL=http://localhost:5431 pnpm exec playwright test
--project=cloud
browser_tests/tests/dialogs/hostedBillingDestination.spec.ts
--reporter=list`, against
`VITE_BILLING_WEB_URL=https://billing-web.example pnpm dev:cloud` | `4
passed (4.6s)` — settings on both destinations, plus the two new
avatar-menu cases: `opens the in-app pricing table from the avatar menu
while the destination is stripe` and `opens the billing-web pricing
entry alone from the avatar menu while the destination is billing_web` |

Billing SDK track FE-2210 ([implementation plan
V2](https://app.notion.com/p/3d86d73d36508152b92cdbdfdfe83ac8)). Hybrid
model: top-up in-app, subscription management / invoices / payment
methods on the hosted billing app.

| Phase | Item | Ticket | Status |
| --- | --- | --- | --- |
| 1-2 | Session core, transport, readers | FE-2211/2212/2213 | merged |
| 3 | Operation lifecycle, commands, eight-state projection |
FE-2227/2214/2223 | merged (#17655) |
| 4 | `@comfyorg/account-ui` composables + `CheckoutSteps` | FE-2215 |
merged (#17662, #17663) |
| 5 slice 1 | Top-up through the SDK behind `billing_sdk_topup_enabled`
| FE-2216 | merged (#17665) |
| rollout C | `hosted_billing_destination` server flag read by the host
| FE-2218 | merged (#17716) |
| rollout C | `hostedDestination` port on the lifecycle, value on
operation state | FE-2210/2218 | #17783 (review) |
| 7 prep | Scope-source port + credentialed transport (BFF / cookie
hosts) | FE-2218 | merged (#17782) |
| 7 prep | `@comfyorg/account` → `@comfyorg/account-core` rename |
FE-2218 | #17851 (review) |
| 7 prep | `billing-contract` route builder + `return_to` registry |
FE-2218 | merged (#17795) |
| 3A-3 | Workshop adapter over `createHostedTopupCheckout` | FE-2214 |
merged (#17793) |
| 8 core | `previewSubscribe` command | FE-2331 | merged (#17797) |
| 8 core | Plans + saved payment-methods readers | FE-2331 | merged
(#17798) |
| 8 ui | account-ui composables (`usePlans`, `usePaymentMethods`,
`usePreviewSubscribe`) | FE-2331 | merged (#17798) |
| 7 | billing-web own-origin session, sign-in, SDK composition | FE-2218
| merged (#17798) |
| 7 | billing-web unit tests in CI (`ci-billing-web-unit.yaml`) |
FE-2218 | merged (#17827, #17844) |
| 7 | ingest CORS + top-up return hosts for billing.comfy.org and its
previews (Comfy-Org/cloud) | FE-2218 | merged (Comfy-Org/cloud#9512) |
| 8 ui | billing-web `/v1` entry routing + subscription / payment-method
surfaces | FE-2331 | merged (#17798) |
| 7 | npm publish (`ingest-types`, `account-core`, `billing-contract`),
Platform install, billing-web live top-up | FE-2218 | todo |
| 6 | Contract tests per generated schema (package layer) | FE-2217 |
| 6 | Live E2E per flow × consumer + evidence table | FE-2217 | todo
(needs staging flags) |
| 5 slice 2a | Cancel, resubscribe and payment portal through the SDK
behind `billing_sdk_subscription_enabled` | FE-2216 | #17853 (review) |
| 5 slice 2b | Subscribe and plan change through the SDK, priced by the
server | FE-2216 | #17856 (review; parent of this PR) |
| 7 / rollout C | Host mints billing-web `/v1/<intent>` entries with
`return_to` when `hosted_billing_destination` is `billing_web` | FE-2218
| **this PR** |
| follow-up | One `needsCustomerAttention` predicate (from the #17665
review) | FE-2216 | merged (#17792) |
| follow-up | Opaque `BillingServerCode` (from the #17656 review) |
FE-2227 | merged (#17794) |
| follow-up | `useCredits` clears on `SUPERSEDED` (from the #17799
review) | FE-2215 | merged (#17824) |
| follow-up | credits / status / capabilities readers fence a late
failure as `SUPERSEDED` (from the #17798 review) | FE-2331 | merged
(#17828) |

```mermaid
flowchart LR
  P3["Phase 3 core lifecycle (merged)"]
  P4["Phase 4 account-ui (merged)"]
  P5["Phase 5 slice 1 top-up flag (merged)"]
  FC["PR 17716 hosted_billing_destination flag (merged)"]
  HD["PR 17783 hostedDestination port"]
  SS["PR 17782 scope-source port + credentialed transport"]
  RN["account-core rename"]
  RB["billing-contract route builder + return_to"]
  WS["Workshop adapter"]
  P8PV["previewSubscribe command"]
  P8RD["plans + payment-methods readers"]
  P8["account-ui hosted composables"]
  BWS["billing-web session + sign-in"]
  BWV["billing-web /v1 surfaces"]
  CORS["cloud PR 9512 ingest CORS + return hosts"]
  PUB["npm publish account-core / billing-contract"]
  P7["Phase 7 host proof: Platform + billing-web live"]
  P6C["Phase 6 contract tests"]
  P6["Phase 6 live evidence"]
  S2A["PR 17853 slice 2a cancel / resubscribe / portal rail"]
  S2B["PR 17856 slice 2b subscribe + plan change"]
  LC["Layer C: host mints billing-web entries"]
  FU9["customer-attention predicate"]
  FU11["opaque BillingServerCode"]
  FU12["useCredits clears on SUPERSEDED"]
  FU13["reader late-failure fence"]
  P3 --> HD
  FC --> HD
  HD --> RB
  P3 --> SS
  SS --> P7
  RB --> P7
  P3 --> RN
  RN --> PUB
  RB --> PUB
  PUB --> P7
  P3 --> P8PV
  P3 --> P8RD
  P8PV --> P8
  P8RD --> P8
  P4 --> P8
  P8 --> S2B
  HD --> S2A
  S2A --> S2B
  S2B --> LC
  RB --> LC
  HD --> LC
  LC --> P7
  P8 --> BWS
  BWS --> BWV
  RB --> BWV
  BWV --> P7
  CORS --> P7
  P5 --> P6
  P3 --> P6C
  P5 --> WS
  P5 --> FU9
  P3 --> FU11
  P4 --> FU12
  P3 --> FU13
  style P3 fill:#d4edda,stroke:#155724
  style P4 fill:#d4edda,stroke:#155724
  style P5 fill:#d4edda,stroke:#155724
  style FC fill:#d4edda,stroke:#155724
  style SS fill:#d4edda,stroke:#155724
  style RB fill:#d4edda,stroke:#155724
  style WS fill:#d4edda,stroke:#155724
  style FU9 fill:#d4edda,stroke:#155724
  style BWV fill:#d4edda,stroke:#155724
  style BWS fill:#d4edda,stroke:#155724
  style P8 fill:#d4edda,stroke:#155724
  style P8RD fill:#d4edda,stroke:#155724
  style CORS fill:#d4edda,stroke:#155724
  style FU13 fill:#d4edda,stroke:#155724
  style FU12 fill:#d4edda,stroke:#155724
  style FU11 fill:#d4edda,stroke:#155724
  style P8PV fill:#d4edda,stroke:#155724
  style LC stroke:#0366d6,stroke-width:4px
```
pull Bot pushed a commit to Mu-L/ComfyUI_frontend that referenced this pull request Sep 17, 2026
…contract and ingest-types (Comfy-Org#17882)

## Why

`@comfyorg/account-core`, `@comfyorg/billing-contract` and
`@comfyorg/ingest-types` are about to be installed by Platform from the
public registry, and today none of them can be packed: `exports` point
at `src/*.ts`, there is no `files` allowlist, no build, and the core
still reaches into a private workspace utility. The release workflows on
Comfy-Org#17881 assume `build` and `smoke:pack` exist; this PR is the part that
makes a tarball installable in plain Node.

Built on Comfy-Org#17854 (auth Vue surface → `account-ui`, now merged) so the
core builds from a Vue-free tree, and it reproduces Maanil's Comfy-Org#17838 /
Comfy-Org#17839 / Comfy-Org#17840 on the renamed tree as agreed in the review thread
there. Base is `main`.

## How

- **Private-utility cut** — the one remaining reach out of the core was
`turnstileScript.ts` →
`@comfyorg/shared-frontend-utils/loadExternalScript`. The loader is now
package-owned (`packages/account-core/src/loadExternalScript.ts`,
byte-identical) and `@comfyorg/shared-frontend-utils` leaves the core's
dependencies. `publishBoundary.test.ts` fails on any future `workspace:`
dependency that is not itself published (`@comfyorg/ingest-types` is the
only allowed one).
- **Manifests** — `files: ["dist"]`, `sideEffects: false`,
`repository`/`homepage`/`author`, MIT `LICENSE` per package,
`publishConfig.exports` mapping every dev `exports` entry to `dist/*.js`
+ `.d.ts`, `./package.json` export, `access: public`.
`@comfyorg/ingest-types` moves `zod` to a peer so a consumer never gets
two zod copies. `private: true` stays on all three (`ingest-types` had
no `private` at all; it now has the latch). Flipping `private` is a
one-line change per manifest in a later reviewed PR.
- **Build** — `tsconfig.build.json` per package (`declaration`,
`noEmitOnError`, `types: []`, tests and fixtures excluded), `build` =
`clean` + `tsc -p`, `prepack` runs it. Relative imports carry `.js` so
the emitted ESM resolves under `nodenext`; `openapi-ts.config.ts` sets
`importFileExtension: '.js'` so regeneration keeps it.
- **Smoke pack** — `scripts/smokePack.ts` (run as `pnpm --filter
@comfyorg/account-core smoke:pack`) packs all three, checks each tarball
(no source/test/fixture files, every export target present, no
unrewritten `catalog:`/`workspace:`), installs them into a throwaway npm
project, imports all 21 entries from plain Node ESM, and type-checks a
`nodenext` consumer. Dropping one `.js` extension makes the typed step
fail with `TS2835`, which the plain-Node step alone would not catch.
- **CI** — `ci-packages-pack.yaml` on `pull_request` for the three
package paths: matrix job per package (typecheck → build → `check:pack`)
plus one `smoke-consumer` job. The tarball rules live in one pure
module, `publishableTarball.ts`, with its own test file; the CLI and the
smoke test are two entry points onto it, so CI and the smoke test cannot
drift.

Deliberate divergences from Comfy-Org#17839: no `region` export and no deletion
in `shared-frontend-utils/networkUtil.ts` (the region gate moved to
`account-ui` with the Vue surface and three app suites still import it);
`createScriptLoader` stays in the shared package for its three
`src/platform` callers.

Open point: the root `LICENSE` is GPL-3.0 while all three manifests
already declare MIT (as `@comfyorg/design-system` publishes). Without a
per-package file pnpm would inject the GPL text into a tarball whose
manifest says MIT, so the MIT files fix the actual defect; whether the
SDK packages should be MIT at all is a call for the reviewer to confirm.

## AS-IS / TO-BE

No UI change; packages, scripts and CI only.

- AS-IS: `pnpm pack` on any of the three ships `src/*.ts` (or nothing)
with `exports` a consumer cannot resolve, and the core depends on a
private workspace package.
- TO-BE: `smoke:pack` proves the three tarballs install and import from
plain Node with types, and CI runs that proof on every change to the
packages.

## Testing

| Check | Result |
| --- | --- |
| `build` account-core / billing-contract / ingest-types | 92 / 18 / 6
dist files |
| `smoke:pack` | 3 packed, 21 entries imported under Node ESM,
`nodenext` tsc clean |
| vitest account-core / account-ui / billing-contract / billing-web |
675 / 79 / 62 / 90 pass |
| `pnpm typecheck`, `pnpm lint`, `pnpm format:check`, `pnpm knip` (with
`dist` on disk) | exit 0 |
| `yamllint` on the new workflow | clean |

## Where this sits in the plan

Billing SDK track FE-2210 ([implementation plan
V2](https://app.notion.com/p/3d86d73d36508152b92cdbdfdfe83ac8)). Hybrid
model: top-up in-app, subscription management / invoices / payment
methods on the hosted billing app.

| Phase | Item | Ticket | Status |
| --- | --- | --- | --- |
| 1-2 | Session core, transport, readers | FE-2211/2212/2213 | merged |
| 3 | Operation lifecycle, commands, eight-state projection |
FE-2227/2214/2223 | merged (Comfy-Org#17655) |
| 4 | `@comfyorg/account-ui` composables + `CheckoutSteps` | FE-2215 |
merged (Comfy-Org#17662, Comfy-Org#17663) |
| 5 slice 1 | Top-up through the SDK behind `billing_sdk_topup_enabled`
| FE-2216 | merged (Comfy-Org#17665) |
| rollout C | `hosted_billing_destination` server flag read by the host
| FE-2218 | merged (Comfy-Org#17716) |
| rollout C | `hostedDestination` port on the lifecycle, value on
operation state | FE-2210/2218 | Comfy-Org#17783 (review, carries slice 2a) |
| 7 prep | Scope-source port + credentialed transport (BFF / cookie
hosts) | FE-2218 | merged (Comfy-Org#17782) |
| 7 prep | `@comfyorg/account` → `@comfyorg/account-core` rename |
FE-2218 | merged (Comfy-Org#17851) |
| 7 prep | Auth Vue surface → `account-ui`; core Vue-free by
construction | FE-2215 | merged (Comfy-Org#17854) |
| 7 prep | `billing-contract` route builder + `return_to` registry |
FE-2218 | merged (Comfy-Org#17795) |
| 3A-3 | Workshop adapter over `createHostedTopupCheckout` | FE-2214 |
merged (Comfy-Org#17793) |
| 8 core | `previewSubscribe` command | FE-2331 | merged (Comfy-Org#17797) |
| 8 core | Plans + saved payment-methods readers | FE-2331 | merged
(Comfy-Org#17798) |
| 8 ui | account-ui composables (`usePlans`, `usePaymentMethods`,
`usePreviewSubscribe`) | FE-2331 | merged (Comfy-Org#17798) |
| 7 | billing-web own-origin session, sign-in, SDK composition | FE-2218
| merged (Comfy-Org#17798) |
| 7 | billing-web unit tests in CI (`ci-billing-web-unit.yaml`) |
FE-2218 | merged (Comfy-Org#17827, Comfy-Org#17844) |
| 7 | ingest CORS + top-up return hosts for billing.comfy.org and its
previews (Comfy-Org/cloud) | FE-2218 | merged (Comfy-Org/cloud#9512) |
| 8 ui | billing-web `/v1` entry routing + subscription / payment-method
surfaces | FE-2331 | merged (Comfy-Org#17798) |
| 7 | Package release workflows + versioning ADR (bump PR → publish on
merge, snapshots) | FE-2218 | Comfy-Org#17881 (review) |
| 7 | Publish readiness: dist build, files allowlist, pack smoke test,
private-utility cut | FE-2218 | **this PR** |
| 7 | First publish (`private` off), Platform install, billing-web live
top-up | FE-2218 | todo |
| 6 | Contract tests per generated schema (package layer) | FE-2217 |
Comfy-Org#17829 (review) |
| 6 | Live E2E per flow × consumer + evidence table | FE-2217 | todo
(needs staging flags) |
| 5 slice 2 | Subscription flows through the SDK | FE-2216 | Comfy-Org#17856 /
Comfy-Org#17860 (review) |
| follow-up | One `needsCustomerAttention` predicate (from the Comfy-Org#17665
review) | FE-2216 | merged (Comfy-Org#17792) |
| follow-up | Opaque `BillingServerCode` (from the Comfy-Org#17656 review) |
FE-2227 | merged (Comfy-Org#17794) |
| follow-up | `useCredits` clears on `SUPERSEDED` (from the Comfy-Org#17799
review) | FE-2215 | merged (Comfy-Org#17824) |
| follow-up | credits / status / capabilities readers fence a late
failure as `SUPERSEDED` (from the Comfy-Org#17798 review) | FE-2331 | merged
(Comfy-Org#17828) |

```mermaid
flowchart LR
  P3["Phase 3 core lifecycle (merged)"]
  P4["Phase 4 account-ui (merged)"]
  P5["Phase 5 slice 1 top-up flag (merged)"]
  FC["PR 17716 hosted_billing_destination flag (merged)"]
  HD["PR 17783 hostedDestination port"]
  SS["PR 17782 scope-source port + credentialed transport"]
  RN["account-core rename (merged)"]
  AV["auth Vue surface to account-ui (merged)"]
  RB["billing-contract route builder + return_to"]
  WS["Workshop adapter"]
  P8PV["previewSubscribe command"]
  P8RD["plans + payment-methods readers"]
  P8["account-ui hosted composables"]
  BWS["billing-web session + sign-in"]
  BWV["billing-web /v1 surfaces"]
  CORS["cloud PR 9512 ingest CORS + return hosts"]
  RW["PR 17881 release workflows + ADR"]
  PR["publish readiness: dist, files, smoke pack"]
  PUB["first publish account-core / billing-contract / ingest-types"]
  P7["Phase 7 host proof: Platform + billing-web live"]
  P6C["Phase 6 contract tests"]
  P6["Phase 6 live evidence"]
  S2["Phase 5 slice 2 subscription"]
  FU9["customer-attention predicate"]
  FU11["opaque BillingServerCode"]
  FU12["useCredits clears on SUPERSEDED"]
  FU13["reader late-failure fence"]
  P3 --> HD
  FC --> HD
  HD --> RB
  P3 --> SS
  SS --> P7
  RB --> P7
  P3 --> RN
  RN --> AV
  AV --> PR
  RW --> PUB
  PR --> PUB
  RB --> PUB
  PUB --> P7
  P3 --> P8PV
  P3 --> P8RD
  P8PV --> P8
  P8RD --> P8
  P4 --> P8
  P8 --> S2
  P8 --> BWS
  BWS --> BWV
  RB --> BWV
  BWV --> P7
  CORS --> P7
  P5 --> P6
  P3 --> P6C
  P5 --> WS
  P5 --> FU9
  P3 --> FU11
  P4 --> FU12
  P3 --> FU13
  style P3 fill:#d4edda,stroke:#155724
  style P4 fill:#d4edda,stroke:#155724
  style P5 fill:#d4edda,stroke:#155724
  style FC fill:#d4edda,stroke:#155724
  style SS fill:#d4edda,stroke:#155724
  style RB fill:#d4edda,stroke:#155724
  style WS fill:#d4edda,stroke:#155724
  style FU9 fill:#d4edda,stroke:#155724
  style BWV fill:#d4edda,stroke:#155724
  style BWS fill:#d4edda,stroke:#155724
  style P8 fill:#d4edda,stroke:#155724
  style P8RD fill:#d4edda,stroke:#155724
  style CORS fill:#d4edda,stroke:#155724
  style FU13 fill:#d4edda,stroke:#155724
  style FU12 fill:#d4edda,stroke:#155724
  style FU11 fill:#d4edda,stroke:#155724
  style P8PV fill:#d4edda,stroke:#155724
  style RN fill:#d4edda,stroke:#155724
  style AV fill:#d4edda,stroke:#155724
  style PR stroke:#0366d6,stroke-width:4px
```
pull Bot pushed a commit to Mu-L/ComfyUI_frontend that referenced this pull request Sep 17, 2026
…codes (Comfy-Org#17829)

Linear FE-2217.

## Why

The billing SDK core decodes generated zod schemas from
`@comfyorg/ingest-types/zod`, which a bot regenerates from the cloud
OpenAPI whenever the backend moves. Today a regen that renames a field,
drops it, or widens an enum the reducer switches on surfaces either as a
typecheck error somewhere deep in the core or, worse, as a runtime
`MALFORMED_RESPONSE` in front of a customer mid-payment. Nothing states,
in one readable place, which fields of which schema the SDK actually
depends on.

This adds a contract test per generated schema the core decodes. Each
pins the fields the core reads and the enum members it branches on, at
the type level and at parse time, so a regen that changes one of them
fails a named block whose name says what broke — the parse rows under
`vitest run`, the `expectTypeOf` exhaustiveness pins under the package
typecheck. A failure here means the backend contract moved: fix the SDK,
not the test.

These are pins, not behaviour: reader and command behaviour stays
covered by the existing `credits.test.ts`, `status.test.ts`,
`capabilities.test.ts`, `operationState.test.ts`,
`subscriptionCommands.test.ts`, and `topup.test.ts`.

## How

New folder `packages/account-core/src/core/billing/contracts/`, one file
per endpoint contract, picked up by the package's existing
`src/core/**/*.{test,spec}.ts` include. Each file holds a canonical
fixture typed as `z.input<typeof schema>` built by a small typed builder
(no casts), parses it with `safeParse`, pins the output type with
`expectTypeOf`, and runs one `it.for` row per enum value the SDK
branches on.

| Schema | Module that decodes it | Fields pinned |
| --- | --- | --- |
| `zBillingBalanceResponse` | `credits.ts` (read by `topup.ts`,
`balanceWatch.ts`) | `amount_micros` as a number; the four optional
breakdown micros |
| `zBillingStatusResponse` | `status.ts` (read by
`operationLifecycle.ts`, `subscriptionCommands.ts`, `presentation.ts`) |
`billing_rail` (3), `pending_billing_op_id`, `pending_billing_op_type`
(2), `action_url`, `payment_intent_client_secret`, `is_active`,
`subscription_tier` (7), `subscription_status` (3) |
| `zBillingCapabilitiesResponse`, `zBillingCapabilities`,
`zBillingCapabilityScope`, `zBillingCapabilityRolloutDefaults` |
`capabilities.ts` (which parses the three named pieces, not the response
schema) | the five response keys the reader recomposes into its own
schema, reading `expires_at` as a plain string and `revision` as a
number; all seven capability booleans; `resolved_for.user_id` /
`workspace_id`; `expires_at`; `revision` as an int64 bounded to the
JavaScript-safe range the reader reads it back as a number over;
`denied_reasons` absent from the contract, which is why
`capabilityDenials.ts` decodes it off the raw body |
| `zBillingOpStatusResponse` | `operationLifecycle.ts`,
`operationState.ts` | `id`; `status` (the 4 the reducer handles);
`authentication_state` (the 5 it reads or assigns); `decline_reason` (8,
incl. the `generic` fallback); `recovery_action` (4); `phase` (3);
`action_url`; `payment_intent_client_secret`; `retryable` optional |
| `zErrorResponse` | `billingErrorBody.ts` | `code` as an open string
the commands match against their own closed set; a body without
`message` yields no code |
| `zSubscribeRequest`, `zSubscribeResponse` | `subscriptionCommands.ts`
| `confirmation_token`, `saved_payment_method_id` (`pm_` prefix),
`idempotency_key`, `confirm_reactivation`; `billing_op_id`, `status`
(3), optional `payment_method_url` |
| `zResubscribeResponse` | `subscriptionCommands.ts` | `billing_op_id`
regardless of `status` (2) |
| `zCancelSubscriptionResponse2` | `subscriptionCommands.ts` |
`billing_op_id` on both members of the response union |
| `zPaymentPortalResponse` | `subscriptionCommands.ts` | `url` required,
and not https-checked by the schema, which is why the command re-checks
it |
| `zPreviewSubscribeRequest`, `zPreviewSubscribeResponse` |
`subscriptionCommands.ts` | `plan_slug` required and the three optional
request fields; `allowed`, `is_immediate`, `effective_at`,
`transition_type` (4), the int64 money fields and their JSON-number
coercion, `discounts`, `requires_reactivation_confirmation` |
| `zCreateTopupRequest`, `zCreateTopupResponse` | `topup.ts` |
`amount_cents` minimum and its int64 coercion of the JSON number the
command validates but does not send; `idempotency_key`; `billing_op_id`
regardless of `status` (3) |
| `zCreateTopupCheckoutRequest`, `zCreateTopupCheckoutResponse` |
`topup.ts` | the amount bounds and the `return_url` URL rule, pinned by
the issue **path** the command reads to tell the two apart;
`checkout_url` required, `session_id` optional |

`capabilityDenials.ts` is the one billing module that decodes without a
generated schema — deliberately, since a strict enum parse would lose
the whole capability set the first time the server names an unfamiliar
policy branch. Its absence from the generated contract is pinned in
`billingCapabilities.contract.test.ts`.

## AS-IS / TO-BE

No UI. A regenerated `zBillingOpStatusResponse` that adds a fifth
`status`:

- AS-IS: the new value falls through `terminalFromStatus` into the
pending branch; the operation polls until its budget runs out and
reports `timed_out`.
- TO-BE: `billingOpStatus.contract.test.ts` fails on the regen PR,
naming the reducer as what needs updating. Two gates, and which one
fires depends on the pin: the enum rows (`accepts the %s status`) fail
under `vitest run`, while the exhaustiveness pin at
`billingOpStatus.contract.test.ts:36` sits at module scope and fails as
a TS2344 under the package typecheck, not in the test run.

## Testing

- `cd packages/account-core && vitest run src/core/billing/contracts` —
12 files, 90 tests, all passing. The type pins are not among them: they
sit at module scope and fail `pnpm --filter @comfyorg/account-core
typecheck` instead, because nothing here runs `vitest --typecheck`.
- `cd packages/account-core && tsc --noEmit` — clean
- `pnpm typecheck` — passing; verified the type pins bite by injecting a
spurious enum member and watching `expectTypeOf` fail with TS2344
- `pnpm lint`, `pnpm format`, `pnpm knip` — passing
- `fallow audit --changed-since origin/main` — no issues in the 13
changed files
## Where this sits in the plan

Billing SDK track FE-2210 ([implementation plan
V2](https://app.notion.com/p/3d86d73d36508152b92cdbdfdfe83ac8)). Hybrid
model: top-up in-app, subscription management / invoices / payment
methods on the hosted billing app.

| Phase | Item | Ticket | Status |
| --- | --- | --- | --- |
| 1-2 | Session core, transport, readers | FE-2211/2212/2213 | merged |
| 3 | Operation lifecycle, commands, eight-state projection |
FE-2227/2214/2223 | merged (Comfy-Org#17655) |
| 4 | `@comfyorg/account-ui` composables + `CheckoutSteps` | FE-2215 |
merged (Comfy-Org#17662, Comfy-Org#17663) |
| 5 slice 1 | Top-up through the SDK behind `billing_sdk_topup_enabled`
| FE-2216 | merged (Comfy-Org#17665) |
| rollout C | `hosted_billing_destination` server flag read by the host
| FE-2218 | merged (Comfy-Org#17716) |
| rollout C | `hostedDestination` port on the lifecycle, value on
operation state | FE-2210/2218 | open (Comfy-Org#17783, carries slice 2a) |
| 7 prep | Scope-source port + credentialed transport (BFF / cookie
hosts) | FE-2218 | merged (Comfy-Org#17782) |
| 7 prep | `@comfyorg/account` → `@comfyorg/account-core` rename |
FE-2218 | merged (Comfy-Org#17851) — this PR sits on it |
| 7 prep | `billing-contract` route builder + `return_to` registry |
FE-2218 | merged (Comfy-Org#17795) |
| 3A-3 | Workshop adapter over `createHostedTopupCheckout` | FE-2214 |
merged (Comfy-Org#17793) |
| 8 core | `previewSubscribe` command | FE-2331 | merged (Comfy-Org#17797) |
| 8 core | Plans + saved payment-methods readers | FE-2331 | merged
(Comfy-Org#17798) |
| 8 ui | account-ui composables (`usePlans`, `usePaymentMethods`,
`usePreviewSubscribe`) | FE-2331 | merged (Comfy-Org#17798) |
| 7 | billing-web own-origin session, sign-in, SDK composition | FE-2218
| merged (Comfy-Org#17798) |
| 7 | billing-web unit tests in CI (`ci-billing-web-unit.yaml`) |
FE-2218 | merged (Comfy-Org#17827, Comfy-Org#17844) |
| 7 | ingest CORS + top-up return hosts for billing.comfy.org and its
previews (Comfy-Org/cloud) | FE-2218 | merged (Comfy-Org/cloud#9512) |
| 8 ui | billing-web `/v1` entry routing + subscription / payment-method
surfaces | FE-2331 | merged (Comfy-Org#17798) |
| 7 | Publish readiness: dist build, files allowlist, pack smoke test |
FE-2218 | merged (Comfy-Org#17882) |
| 7 | Package release workflows + versioning ADR | FE-2218 | open
(Comfy-Org#17881) |
| 7 | First publish (`private` off), Platform install, billing-web live
top-up | FE-2218 | todo |
| 6 | Contract tests per generated schema (package layer) | FE-2217 |
**this PR** |
| 6 | Live E2E per flow × consumer + evidence table | FE-2217 | todo
(needs staging flags) |
| 5 slice 2 | Subscription flows through the SDK | FE-2216 | open
(Comfy-Org#17856, Comfy-Org#17860) |
| follow-up | One `needsCustomerAttention` predicate (from the Comfy-Org#17665
review) | FE-2216 | merged (Comfy-Org#17792) |
| follow-up | Opaque `BillingServerCode` (from the Comfy-Org#17656 review) |
FE-2227 | merged (Comfy-Org#17794) |
| follow-up | `useCredits` clears on `SUPERSEDED` (from the Comfy-Org#17799
review) | FE-2215 | merged (Comfy-Org#17824) |
| follow-up | credits / status / capabilities readers fence a late
failure as `SUPERSEDED` (from the Comfy-Org#17798 review) | FE-2331 | open
(Comfy-Org#17828) |

```mermaid
flowchart LR
  P3["Phase 3 core lifecycle (merged)"]
  P4["Phase 4 account-ui (merged)"]
  P5["Phase 5 slice 1 top-up flag (merged)"]
  FC["PR 17716 hosted_billing_destination flag (merged)"]
  HD["PR 17783 hostedDestination port"]
  SS["PR 17782 scope-source port + credentialed transport"]
  RN["account-core rename"]
  RB["billing-contract route builder + return_to"]
  WS["Workshop adapter"]
  P8PV["previewSubscribe command"]
  P8RD["plans + payment-methods readers"]
  P8["account-ui hosted composables"]
  BWS["billing-web session + sign-in"]
  BWV["billing-web /v1 surfaces"]
  CORS["cloud PR 9512 ingest CORS + return hosts"]
  PUB["npm publish account-core / billing-contract"]
  P7["Phase 7 host proof: Platform + billing-web live"]
  P6C["Phase 6 contract tests"]
  P6["Phase 6 live evidence"]
  S2["Phase 5 slice 2 subscription"]
  FU9["customer-attention predicate"]
  FU11["opaque BillingServerCode"]
  FU12["useCredits clears on SUPERSEDED"]
  FU13["reader late-failure fence"]
  P3 --> HD
  FC --> HD
  HD --> RB
  P3 --> SS
  SS --> P7
  RB --> P7
  P3 --> RN
  RN --> PUB
  RB --> PUB
  PUB --> P7
  P3 --> P8PV
  P3 --> P8RD
  P8PV --> P8
  P8RD --> P8
  P4 --> P8
  P8 --> S2
  P8 --> BWS
  BWS --> BWV
  RB --> BWV
  BWV --> P7
  CORS --> P7
  P5 --> P6
  P3 --> P6C
  P5 --> WS
  P5 --> FU9
  P3 --> FU11
  P4 --> FU12
  P3 --> FU13
  style P3 fill:#d4edda,stroke:#155724
  style P4 fill:#d4edda,stroke:#155724
  style P5 fill:#d4edda,stroke:#155724
  style FC fill:#d4edda,stroke:#155724
  style SS fill:#d4edda,stroke:#155724
  style RB fill:#d4edda,stroke:#155724
  style WS fill:#d4edda,stroke:#155724
  style FU9 fill:#d4edda,stroke:#155724
  style P8PV fill:#d4edda,stroke:#155724
  style P6C stroke:#0366d6,stroke-width:4px
```
pull Bot pushed a commit to Penguinjanator/ComfyUI_frontend that referenced this pull request Sep 17, 2026
…ced by the server (Comfy-Org#17856)

Stacked on Comfy-Org#17853 (base branch `jaewon/fe-2216-subscription-rail`),
which stacks on Comfy-Org#17783; merge those first.

## Why

Slice 2a (Comfy-Org#17853) put cancel, resubscribe and the payment portal on the
SDK rail. Subscribe — new subscriptions and plan changes — was left on
the legacy call because the SDK's `subscribe` refused an active
subscription on the client (`active → ALREADY_HELD`) and routed a
scheduled cancel to `resubscribe()`, which carries no plan. Both
contradict what the host already does: `useWorkspaceBilling.subscribe`
posts `/billing/subscribe` whatever the subscription state,
`useSubscriptionCheckout` quotes the change first with
`previewSubscribe`, and the server prices the change, reactivates or
refuses (`REACTIVATION_CONFIRMATION_REQUIRED` exists for exactly that).
Decision (2026-09-16): mirror the host; no product change.

## How

- **Core.** `subscribe()` issues `POST /billing/subscribe` for every
subscription state and never short-circuits; the client-side eligibility
switch, `eligibilityOf` and its type are gone (nothing else read them).
`resubscribe()` stays the explicit "resume" command.
`docs/billing-command-eligibility.md` (the path the module doc already
referenced) now records the route per command and that the status read
decides nothing for subscribe.
- **Core, quote decoding.** The generated zod for the preview coerces
every int64 to `bigint` while the generated TS type for the same fields
is `number`, so the SDK's quote was not assignable to the host's
`PreviewSubscribeResponse`. The cents fields are decoded as `z.number()`
via `.extend` on the generated schemas (the precedent `capabilities.ts`
sets for `revision`; money on this route is bounded to cents well inside
the safe range). The two types are now structurally identical and `pnpm
typecheck` proves the assignment with no hand-written projection.
- **Host.** On the rail (read once per action, as in 2a)
`useWorkspaceBilling.subscribe` maps `SubscribeOptions → SubscribeInput`
field for field (`confirmationToken` / `savedPaymentMethodId` empty →
dropped, as the workspace client does; nothing dropped otherwise) and
runs `sdk.commands.subscribe`; `previewSubscribe` runs
`sdk.commands.previewSubscribe`. Both share 2a's route latch (404 →
legacy once), and every other failure is thrown as a `WorkspaceApiError`
whose `.code` carries the server code verbatim, so
`useSubscriptionCheckout` and `useDowngradeToPersonal` keep branching on
`REACTIVATION_CONFIRMATION_REQUIRED`, `SUBSCRIPTION_PAYMENT_REQUIRED`,
`OUTSTANDING_PAYMENT_REQUIRED`, `TRANSITION_NOT_ALLOWED`,
`PRORATION_QUOTE_EXPIRED`, `SUBSCRIPTION_QUOTE_STALE` unchanged.
- **Customer steps.** The SDK settles the operation inside
`subscribe()`, so nothing else watches it: the store's lifecycle
subscriber now handles non-topup pending states — the existing in-page
challenge driver, and a once-per-operation `window.open(actionUrl)` with
the same popup-blocked toast the checkout shows. Without both, a 3DS
plan change or a `needs_payment_method` answer would time out with
nothing on screen.
- **Settled response.** A settled subscribe projects to the `{
billing_op_id, status: 'subscribed' }` body `handleSubscribeResponse`
already handles; `needs_payment_method` / `pending_payment` never reach
the host because the lifecycle drove them first.
- Not on the rail: `teamSubscriptionCheckoutUtil.ts` calls
`workspaceApi.subscribe` directly and stays legacy on both rails;
`savePendingSubscriptionCheckout` and checkout-journey `billing_op_id`
linking run after settlement rather than at issue, because the SDK does
not surface the issued operation (recovery across reloads is the
lifecycle's `recover()`).

## AS-IS / TO-BE

Same journey on both: `?pricing=creator&cycle=yearly` against an active
`standard-annual` subscription on the `stripe` rail, 1280×800, every
endpoint mocked.

| State | AS-IS — `billing_sdk_subscription_enabled: false` | TO-BE —
`billing_sdk_subscription_enabled: true` |
| --- | --- | --- |
| "Confirm your upgrade" with the quote | <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17856-screenshots/screenshots/as-is-confirm-upgrade.png">
| <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17856-screenshots/screenshots/to-be-confirm-upgrade.png">
|
| "You're all set" after confirming | <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17856-screenshots/screenshots/as-is-all-set.png">
| <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17856-screenshots/screenshots/to-be-all-set.png">
|
| Recorded `subscribe` request (quote above it carries no key on either
rail) | no `Idempotency-Key` <br> <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17856-screenshots/screenshots/as-is-subscribe-headers.png">
| `Idempotency-Key` present and echoed as `idempotency_key` <br> <img
width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17856-screenshots/screenshots/to-be-subscribe-headers.png">
|
| `POST /billing/subscribe` answers 404 | one POST, the click fails
("Request failed with status code 404") <br> <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17856-screenshots/screenshots/as-is-404-fallback.png">
| two POSTs from one click — first with the key → 404, second without →
200, "You're all set" <br> <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17856-screenshots/screenshots/to-be-404-fallback.png">
|
| Server answers `REACTIVATION_CONFIRMATION_REQUIRED` | re-quotes, shows
the reactivation panel and the coded toast <br> <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17856-screenshots/screenshots/as-is-reactivation-required.png">
| identical panel, toast and CTA on the rail <br> <img width="480"
src="https://raw.githubusercontent.com/Comfy-Org/ComfyUI_frontend/assets/pr-17856-screenshots/screenshots/to-be-reactivation-required.png">
|

- AS-IS (flag off): quote and subscribe go through the workspace API; a
3DS or payment-method step is driven by the checkout composable off the
raw response.
- TO-BE (flag on): the same screens and copy; quote and subscribe go
through the SDK transport (`Idempotency-Key` on the subscribe POST),
settlement through the operation lifecycle; a 404 falls back to the
legacy call.

## Testing

| Gate | Result |
| --- | --- |
| `packages/account` vitest | 39 files, 634 tests (new: active plan
change issues the request; canceled carries `plan_slug` +
`confirm_reactivation`; `REACTIVATION_CONFIRMATION_REQUIRED` surfaces
coded) |
| host vitest (billing sdk, composables/billing, workspace composables +
stores, feature flags) | 41 files, 1151 tests |
| `pnpm typecheck`, `typecheck:browser`, `lint`, `format`, `knip` | exit
0 |
| `fallow audit --changed-since origin/jaewon/fe-2216-subscription-rail`
| no issues in 10 changed files, complexity 0, duplication 0 |
| Playwright cloud: `planChangeSdkRail.spec.ts` (3) +
`cancelSubscriptionSdkRail.spec.ts` (3) | `6 passed (11.5s)` —
`PLAYWRIGHT_TEST_URL=http://localhost:5173 pnpm exec playwright test
--project=cloud browser_tests/tests/dialogs/planChangeSdkRail.spec.ts
browser_tests/tests/dialogs/cancelSubscriptionSdkRail.spec.ts
--reporter=list` against a `pnpm dev:cloud` vite server, all endpoints
mocked |

## Where this sits in the plan

Billing SDK track FE-2210 ([implementation plan
V2](https://app.notion.com/p/3d86d73d36508152b92cdbdfdfe83ac8)). Hybrid
model: top-up in-app, subscription management / invoices / payment
methods on the hosted billing app.

| Phase | Item | Ticket | Status |
| --- | --- | --- | --- |
| 1-2 | Session core, transport, readers | FE-2211/2212/2213 | merged |
| 3 | Operation lifecycle, commands, eight-state projection |
FE-2227/2214/2223 | merged (Comfy-Org#17655) |
| 4 | `@comfyorg/account-ui` composables + `CheckoutSteps` | FE-2215 |
merged (Comfy-Org#17662, Comfy-Org#17663) |
| 5 slice 1 | Top-up through the SDK behind `billing_sdk_topup_enabled`
| FE-2216 | merged (Comfy-Org#17665) |
| rollout C | `hosted_billing_destination` server flag read by the host
| FE-2218 | merged (Comfy-Org#17716) |
| rollout C | `hostedDestination` port on the lifecycle, value on
operation state | FE-2210/2218 | Comfy-Org#17783 (review) |
| 7 prep | Scope-source port + credentialed transport (BFF / cookie
hosts) | FE-2218 | merged (Comfy-Org#17782) |
| 7 prep | `@comfyorg/account` → `@comfyorg/account-core` rename |
FE-2218 | Comfy-Org#17851 (review) |
| 7 prep | `billing-contract` route builder + `return_to` registry |
FE-2218 | merged (Comfy-Org#17795) |
| 3A-3 | Workshop adapter over `createHostedTopupCheckout` | FE-2214 |
merged (Comfy-Org#17793) |
| 8 core | `previewSubscribe` command | FE-2331 | merged (Comfy-Org#17797) |
| 8 core | Plans + saved payment-methods readers | FE-2331 | merged
(Comfy-Org#17798) |
| 8 ui | account-ui composables (`usePlans`, `usePaymentMethods`,
`usePreviewSubscribe`) | FE-2331 | merged (Comfy-Org#17798) |
| 7 | billing-web own-origin session, sign-in, SDK composition | FE-2218
| merged (Comfy-Org#17798) |
| 7 | billing-web unit tests in CI (`ci-billing-web-unit.yaml`) |
FE-2218 | merged (Comfy-Org#17827, Comfy-Org#17844) |
| 7 | ingest CORS + top-up return hosts for billing.comfy.org and its
previews (Comfy-Org/cloud) | FE-2218 | merged (Comfy-Org/cloud#9512) |
| 8 ui | billing-web `/v1` entry routing + subscription / payment-method
surfaces | FE-2331 | merged (Comfy-Org#17798) |
| 7 | npm publish (`ingest-types`, `account-core`, `billing-contract`),
Platform install, billing-web live top-up | FE-2218 | todo |
| 6 | Contract tests per generated schema (package layer) | FE-2217 |
Comfy-Org#17829 (review) |
| 6 | Live E2E per flow × consumer + evidence table | FE-2217 | todo
(needs staging flags) |
| 5 slice 2a | Cancel, resubscribe and payment portal through the SDK
behind `billing_sdk_subscription_enabled` | FE-2216 | Comfy-Org#17853 (review;
parent of this PR) |
| 5 slice 2b | Subscribe and plan change through the SDK: quote, then
subscribe; the SDK never short-circuits on the client | FE-2216 | **this
PR** |
| follow-up | One `needsCustomerAttention` predicate (from the Comfy-Org#17665
review) | FE-2216 | merged (Comfy-Org#17792) |
| follow-up | Opaque `BillingServerCode` (from the Comfy-Org#17656 review) |
FE-2227 | merged (Comfy-Org#17794) |
| follow-up | `useCredits` clears on `SUPERSEDED` (from the Comfy-Org#17799
review) | FE-2215 | merged (Comfy-Org#17824) |
| follow-up | credits / status / capabilities readers fence a late
failure as `SUPERSEDED` (from the Comfy-Org#17798 review) | FE-2331 | merged
(Comfy-Org#17828) |

```mermaid
flowchart LR
  P3["Phase 3 core lifecycle (merged)"]
  P4["Phase 4 account-ui (merged)"]
  P5["Phase 5 slice 1 top-up flag (merged)"]
  FC["PR 17716 hosted_billing_destination flag (merged)"]
  HD["PR 17783 hostedDestination port"]
  SS["PR 17782 scope-source port + credentialed transport"]
  RN["account-core rename"]
  RB["billing-contract route builder + return_to"]
  WS["Workshop adapter"]
  P8PV["previewSubscribe command"]
  P8RD["plans + payment-methods readers"]
  P8["account-ui hosted composables"]
  BWS["billing-web session + sign-in"]
  BWV["billing-web /v1 surfaces"]
  CORS["cloud PR 9512 ingest CORS + return hosts"]
  PUB["npm publish account-core / billing-contract"]
  P7["Phase 7 host proof: Platform + billing-web live"]
  P6C["Phase 6 contract tests"]
  P6["Phase 6 live evidence"]
  S2A["PR 17853 slice 2a cancel / resubscribe / portal rail"]
  S2B["Phase 5 slice 2b subscribe + plan change"]
  FU9["customer-attention predicate"]
  FU11["opaque BillingServerCode"]
  FU12["useCredits clears on SUPERSEDED"]
  FU13["reader late-failure fence"]
  P3 --> HD
  FC --> HD
  HD --> RB
  P3 --> SS
  SS --> P7
  RB --> P7
  P3 --> RN
  RN --> PUB
  RB --> PUB
  PUB --> P7
  P3 --> P8PV
  P3 --> P8RD
  P8PV --> P8
  P8RD --> P8
  P4 --> P8
  P8 --> S2B
  HD --> S2A
  S2A --> S2B
  P8 --> BWS
  BWS --> BWV
  RB --> BWV
  BWV --> P7
  CORS --> P7
  P5 --> P6
  P3 --> P6C
  P5 --> WS
  P5 --> FU9
  P3 --> FU11
  P4 --> FU12
  P3 --> FU13
  style P3 fill:#d4edda,stroke:#155724
  style P4 fill:#d4edda,stroke:#155724
  style P5 fill:#d4edda,stroke:#155724
  style FC fill:#d4edda,stroke:#155724
  style SS fill:#d4edda,stroke:#155724
  style RB fill:#d4edda,stroke:#155724
  style WS fill:#d4edda,stroke:#155724
  style FU9 fill:#d4edda,stroke:#155724
  style BWV fill:#d4edda,stroke:#155724
  style BWS fill:#d4edda,stroke:#155724
  style P8 fill:#d4edda,stroke:#155724
  style P8RD fill:#d4edda,stroke:#155724
  style CORS fill:#d4edda,stroke:#155724
  style FU13 fill:#d4edda,stroke:#155724
  style FU12 fill:#d4edda,stroke:#155724
  style FU11 fill:#d4edda,stroke:#155724
  style P8PV fill:#d4edda,stroke:#155724
  style S2B stroke:#0366d6,stroke-width:4px
```
pull Bot pushed a commit to Penguinjanator/ComfyUI_frontend that referenced this pull request Sep 17, 2026
…Rs, with the versioning ADR (Comfy-Org#17881)

## Why

`@comfyorg/account-core`, `@comfyorg/billing-contract` and
`@comfyorg/ingest-types` are about to be installed by Platform from the
public registry, and the plan had nothing on how their versions are cut.
The monorepo already releases one package (`@comfyorg/design-system`)
through a version-bump PR that publishes on merge; the decision
(2026-09-16) is to follow that pattern for the SDK packages, generalized
over a package input rather than copied, and to defer Changesets with
the revisit conditions written down.

## How

- `version-bump-package.yaml` — `workflow_dispatch` with `package`
(account-core / billing-contract / ingest-types), `version_type`,
`pre_release`; bumps on `main` and opens a `Release`-labelled PR titled
`<package> <version>` (same pinned `create-pull-request` action as the
design-system workflow).
- `publish-package.yaml` — reusable (`workflow_dispatch` +
`workflow_call`): name/version match, an explicit failure while
`"private": true`, `build` and `smoke:pack` via `--if-present` (works
before and after the publish-readiness PR lands), `npm view` skip on an
existing version, `pnpm publish --access public --tag … --provenance`
under `id-token: write`.
- `publish-package-on-merge.yaml` — on a merged `Release` PR touching
one of the three manifests, publishes every package whose `version`
changed against the first parent (matrix), posts the release-links
comment per package and the Slack notice.
- `.github/actions/comment-release-links` — three additive cases so each
package's summary has its own section.
- `packages/{account-core,billing-contract,ingest-types}/package.json` —
`"private": true` removed. Comfy-Org#17882 is merged and its smoke test proves
the three tarballs install from plain Node, so the latch comes off here,
in the same reviewed PR as the machinery that checks it. Nothing
publishes on this merge: the on-merge job needs a `Release` label and a
version change, and neither is present.
-
`docs/adr/RELEASES-PACKAGES-0033-sdk-packages-release-through-version-bump-prs.md`
(+ index): context, the decision and each workflow's rationale, the
versioning policy (`1.0.0-alpha.N` on `next` until the Phase 7 host
proof, then `1.0.0`; generated-contract additions minor, removals major,
decided on the regeneration PR), alternatives (Changesets,
release-please, semantic-release, per-package copies) and the explicit
"when to revisit Changesets" list.

Written against the post-rename names (`packages/account-core`); the
on-merge path filter matches once Comfy-Org#17851 lands. Design-system workflows
are untouched.

Not in this PR, on purpose: the `ingest-types` regeneration bump — the
generator lives in Comfy-Org/cloud; the one-step change needed there is
recorded in the ADR's follow-ups.

**Snapshot publishing is not in this PR.** A `pull_request` run executes
the workflow definition from the pull request's own merge ref, so a
publish step triggered that way is PR-authored code holding `NPM_TOKEN`,
and on `main` today no `pull_request` workflow reaches that secret. It
returns in its own PR, publishing from a `workflow_run` job that runs
the default branch's definition over an artifact the pull-request job
produces.

## AS-IS / TO-BE

No UI change; CI and docs only.

- AS-IS: only `@comfyorg/design-system` has a release path; the SDK
packages have no bump, no publish, no policy.
- TO-BE: one dispatch bumps any of the three, the merged `Release` PR
publishes with provenance, and the ADR records why Changesets waits and
what the snapshot follow-up has to satisfy.

## Testing

| Check | Result |
| --- | --- |
| `actionlint` on the four workflows | 0 findings |
| `zizmor --min-severity medium` | clean apart from the repo-exempt
`actions/checkout@v7` / `setup-node@v6` pins (`.pinact.yaml`);
workflow-level `permissions: contents: read` added after its finding |
| `yamllint` (as `ci-yaml-validation.yaml` runs it) | clean |
| `pnpm adr:check`, `pnpm lint`, `pnpm format:check`, `pnpm knip` | exit
0 |

After the second review round (860ef8a, 8f7972f, 41793c7):
`publish-package.yaml` rejects a prerelease on `latest` and reports
whether it published or skipped, and `version-bump-package.yaml` holds
`account-core` and `billing-contract` on the `1.0.0-alpha.N` line, since
`patch`, `minor` and `major` all turn `1.0.0-alpha.0` into `1.0.0`. The
hardening that round added to the snapshot workflow left with it in
25b09c3.

After the first review round (23b854e, 5985af7): the manual
publish no longer takes a caller-supplied `ref` (it publishes the ref it
was dispatched on), and the ADR scopes the prerelease-first gate to the
hand-written packages, putting `ingest-types` outside it.

The Slack notice posts to `#proj-billing` (`C0BNGQG2LCW`), not the
design-system channel. Open points for review: `--provenance` is new
relative to the design-system publish and is confirmed on the first real
run; Follow-ups, not in this PR: a protected `environment` with required
reviewers and an environment-scoped `NPM_TOKEN` on the publish job (repo
configuration), and the same `ref` removal on
`publish-design-system.yaml`.

## Where this sits in the plan

Billing SDK track FE-2210 ([implementation plan
V2](https://app.notion.com/p/3d86d73d36508152b92cdbdfdfe83ac8)). Hybrid
model: top-up in-app, subscription management / invoices / payment
methods on the hosted billing app.

| Phase | Item | Ticket | Status |
| --- | --- | --- | --- |
| 1-2 | Session core, transport, readers | FE-2211/2212/2213 | merged |
| 3 | Operation lifecycle, commands, eight-state projection |
FE-2227/2214/2223 | merged (Comfy-Org#17655) |
| 4 | `@comfyorg/account-ui` composables + `CheckoutSteps` | FE-2215 |
merged (Comfy-Org#17662, Comfy-Org#17663) |
| 5 slice 1 | Top-up through the SDK behind `billing_sdk_topup_enabled`
| FE-2216 | merged (Comfy-Org#17665) |
| rollout C | `hosted_billing_destination` server flag read by the host
| FE-2218 | merged (Comfy-Org#17716) |
| rollout C | `hostedDestination` port on the lifecycle, value on
operation state | FE-2210/2218 | Comfy-Org#17783 (review, carries slice 2a) |
| 7 prep | Scope-source port + credentialed transport (BFF / cookie
hosts) | FE-2218 | merged (Comfy-Org#17782) |
| 7 prep | `@comfyorg/account` → `@comfyorg/account-core` rename |
FE-2218 | Comfy-Org#17851 (queued) |
| 7 prep | `billing-contract` route builder + `return_to` registry |
FE-2218 | merged (Comfy-Org#17795) |
| 3A-3 | Workshop adapter over `createHostedTopupCheckout` | FE-2214 |
merged (Comfy-Org#17793) |
| 8 core | `previewSubscribe` command | FE-2331 | merged (Comfy-Org#17797) |
| 8 core | Plans + saved payment-methods readers | FE-2331 | merged
(Comfy-Org#17798) |
| 8 ui | account-ui composables (`usePlans`, `usePaymentMethods`,
`usePreviewSubscribe`) | FE-2331 | merged (Comfy-Org#17798) |
| 7 | billing-web own-origin session, sign-in, SDK composition | FE-2218
| merged (Comfy-Org#17798) |
| 7 | billing-web unit tests in CI (`ci-billing-web-unit.yaml`) |
FE-2218 | merged (Comfy-Org#17827, Comfy-Org#17844) |
| 7 | ingest CORS + top-up return hosts for billing.comfy.org and its
previews (Comfy-Org/cloud) | FE-2218 | merged (Comfy-Org/cloud#9512) |
| 8 ui | billing-web `/v1` entry routing + subscription / payment-method
surfaces | FE-2331 | merged (Comfy-Org#17798) |
| 7 | Package release workflows + versioning ADR (bump dispatch →
publish on merge) | FE-2218 | **this PR** |
| 7 | Pre-merge snapshots from a default-branch `workflow_run` job |
FE-2218 | todo (split out of this PR) |
| 7 | Publish readiness: dist build, files allowlist, pack smoke test,
private-utility cut | FE-2218 | merged (Comfy-Org#17882) |
| 7 | `private` off on the three manifests | FE-2218 | **this PR** |
| 7 | First publish (bump PRs: ingest-types, then billing-contract,
account-core), Platform install, billing-web live top-up | FE-2218 |
todo |
| 6 | Contract tests per generated schema (package layer) | FE-2217 |
Comfy-Org#17829 (review) |
| 6 | Live E2E per flow × consumer + evidence table | FE-2217 | todo
(needs staging flags) |
| 5 slice 2 | Subscription flows through the SDK | FE-2216 | Comfy-Org#17856 /
Comfy-Org#17860 (review) |
| follow-up | One `needsCustomerAttention` predicate (from the Comfy-Org#17665
review) | FE-2216 | merged (Comfy-Org#17792) |
| follow-up | Opaque `BillingServerCode` (from the Comfy-Org#17656 review) |
FE-2227 | merged (Comfy-Org#17794) |
| follow-up | `useCredits` clears on `SUPERSEDED` (from the Comfy-Org#17799
review) | FE-2215 | merged (Comfy-Org#17824) |
| follow-up | credits / status / capabilities readers fence a late
failure as `SUPERSEDED` (from the Comfy-Org#17798 review) | FE-2331 | merged
(Comfy-Org#17828) |

```mermaid
flowchart LR
  P3["Phase 3 core lifecycle (merged)"]
  P4["Phase 4 account-ui (merged)"]
  P5["Phase 5 slice 1 top-up flag (merged)"]
  FC["PR 17716 hosted_billing_destination flag (merged)"]
  HD["PR 17783 hostedDestination port"]
  SS["PR 17782 scope-source port + credentialed transport"]
  RN["account-core rename"]
  RB["billing-contract route builder + return_to"]
  WS["Workshop adapter"]
  P8PV["previewSubscribe command"]
  P8RD["plans + payment-methods readers"]
  P8["account-ui hosted composables"]
  BWS["billing-web session + sign-in"]
  BWV["billing-web /v1 surfaces"]
  CORS["cloud PR 9512 ingest CORS + return hosts"]
  RW["release workflows + ADR"]
  PUB["npm publish account-core / billing-contract"]
  P7["Phase 7 host proof: Platform + billing-web live"]
  P6C["Phase 6 contract tests"]
  P6["Phase 6 live evidence"]
  S2["Phase 5 slice 2 subscription"]
  FU9["customer-attention predicate"]
  FU11["opaque BillingServerCode"]
  FU12["useCredits clears on SUPERSEDED"]
  FU13["reader late-failure fence"]
  P3 --> HD
  FC --> HD
  HD --> RB
  P3 --> SS
  SS --> P7
  RB --> P7
  P3 --> RN
  RN --> PUB
  RW --> PUB
  RB --> PUB
  PUB --> P7
  P3 --> P8PV
  P3 --> P8RD
  P8PV --> P8
  P8RD --> P8
  P4 --> P8
  P8 --> S2
  P8 --> BWS
  BWS --> BWV
  RB --> BWV
  BWV --> P7
  CORS --> P7
  P5 --> P6
  P3 --> P6C
  P5 --> WS
  P5 --> FU9
  P3 --> FU11
  P4 --> FU12
  P3 --> FU13
  style P3 fill:#d4edda,stroke:#155724
  style P4 fill:#d4edda,stroke:#155724
  style P5 fill:#d4edda,stroke:#155724
  style FC fill:#d4edda,stroke:#155724
  style SS fill:#d4edda,stroke:#155724
  style RB fill:#d4edda,stroke:#155724
  style WS fill:#d4edda,stroke:#155724
  style FU9 fill:#d4edda,stroke:#155724
  style BWV fill:#d4edda,stroke:#155724
  style BWS fill:#d4edda,stroke:#155724
  style P8 fill:#d4edda,stroke:#155724
  style P8RD fill:#d4edda,stroke:#155724
  style CORS fill:#d4edda,stroke:#155724
  style FU13 fill:#d4edda,stroke:#155724
  style FU12 fill:#d4edda,stroke:#155724
  style FU11 fill:#d4edda,stroke:#155724
  style P8PV fill:#d4edda,stroke:#155724
  style RW stroke:#0366d6,stroke-width:4px
```
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

risk:xhigh PR risk grade (advisory shadow check; grader-owned)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants