From 3c084197c6611b65cddcade5f18d689e60516933 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sat, 19 Sep 2026 21:25:01 +0200
Subject: [PATCH 001/108] chore(deps)!: pin html2rss to master for structured
 validation report

Preview and validate need ValidationReport and Test::Result#validation_issues, which only exist on gem master. html2rss-configs still resolves against that pin.
---
 Gemfile      |  4 ++--
 Gemfile.lock | 64 ++++++++++++++++++++++++++++------------------------
 2 files changed, 37 insertions(+), 31 deletions(-)

diff --git a/Gemfile b/Gemfile
index 6c1c1a75..875094f5 100644
--- a/Gemfile
+++ b/Gemfile
@@ -4,8 +4,8 @@ source 'https://rubygems.org'
 
 git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
 
-gem 'html2rss', '~> 0.30'
-# gem 'html2rss', github: 'html2rss/html2rss', branch: 'master'
+# gem 'html2rss', '~> 0.30'
+gem 'html2rss', github: 'html2rss/html2rss', branch: 'master'
 gem 'html2rss-configs', github: 'html2rss/html2rss-configs'
 
 # Use these instead of the two above (uncomment them) when developing locally:
diff --git a/Gemfile.lock b/Gemfile.lock
index 815ad48e..080b7013 100644
--- a/Gemfile.lock
+++ b/Gemfile.lock
@@ -1,3 +1,27 @@
+GIT
+  remote: https://github.com/html2rss/html2rss
+  revision: 84cad9e9870e8159088c65e0b1a306e7f4ba9026
+  branch: master
+  specs:
+    html2rss (0.30.0)
+      addressable (~> 2.7)
+      brotli
+      dry-validation
+      httpx (~> 1.8)
+      kramdown
+      mcp (~> 1.2)
+      mime-types (> 3.0)
+      nokogiri (>= 1.10, < 2.0)
+      rack (~> 3.0)
+      rackup (~> 2.0)
+      regexp_parser
+      rss
+      sanitize
+      thor
+      tzinfo
+      webrick (~> 1.9)
+      zeitwerk
+
 GIT
   remote: https://github.com/html2rss/html2rss-configs
   revision: 2355ce1b4189b01282acfb99f8e4548fe3ec417a
@@ -69,7 +93,7 @@ GEM
       bigdecimal
       samovar (~> 2.1)
     base64 (0.3.0)
-    bigdecimal (4.1.2)
+    bigdecimal (4.1.3)
     brotli (0.8.0)
     builder (3.3.0)
     climate_control (1.2.0)
@@ -141,26 +165,8 @@ GEM
     fiber-storage (1.0.1)
     hana (1.3.7)
     hashdiff (1.2.1)
-    html2rss (0.30.0)
-      addressable (~> 2.7)
-      brotli
-      dry-validation
-      httpx (~> 1.8)
-      kramdown
-      mcp (~> 1.2)
-      mime-types (> 3.0)
-      nokogiri (>= 1.10, < 2.0)
-      rack (~> 3.0)
-      rackup (~> 2.0)
-      regexp_parser
-      rss
-      sanitize
-      thor
-      tzinfo
-      webrick (~> 1.9)
-      zeitwerk
-    http-2 (1.2.2)
-    httpx (1.8.3)
+    http-2 (1.2.3)
+    httpx (1.8.4)
       http-2 (>= 1.2.0)
     i18n (1.15.2)
       concurrent-ruby (~> 1.0)
@@ -191,7 +197,7 @@ GEM
     loofah (2.25.2)
       crass (~> 1.0.2)
       nokogiri (>= 1.12.0)
-    mcp (1.5.0)
+    mcp (1.5.1)
       json_schemer (>= 2.4)
     mime-types (3.7.0)
       logger
@@ -370,7 +376,7 @@ DEPENDENCIES
   base64
   climate_control
   falcon
-  html2rss (~> 0.30)
+  html2rss!
   html2rss-configs!
   irb
   rack-test
@@ -407,7 +413,7 @@ CHECKSUMS
   async-utilization (0.5.0) sha256=96c347634e09edcbcb7f70cf8c5a1ae058c64d88186341e3f924a44440f95981
   bake (0.25.0) sha256=a47bdc6a26addc048827debc36fe27bb4d5d71ac2958ad910b5386e9baf49869
   base64 (0.3.0) sha256=27337aeabad6ffae05c265c450490628ef3ebd4b67be58257393227588f5a97b
-  bigdecimal (4.1.2) sha256=53d217666027eab4280346fba98e7d5b66baaae1b9c3c1c0ffe89d48188a3fbd
+  bigdecimal (4.1.3) sha256=61ebe1e5e559bdc3cc6f2c0ee7f427321fc838f59611c294356eb04d6e21cf66
   brotli (0.8.0) sha256=0c5a42046b3b603fb109656881147fd76064c034b7d19c1b4fcc32a093a4d55d
   builder (3.3.0) sha256=497918d2f9dca528fdca4b88d84e4ef4387256d984b8154e9d5d3fe5a9c8835f
   climate_control (1.2.0) sha256=36b21896193fa8c8536fa1cd843a07cf8ddbd03aaba43665e26c53ec1bd70aa5
@@ -434,10 +440,10 @@ CHECKSUMS
   fiber-storage (1.0.1) sha256=f48e5b6d8b0be96dac486332b55cee82240057065dc761c1ea692b2e719240e1
   hana (1.3.7) sha256=5425db42d651fea08859811c29d20446f16af196308162894db208cac5ce9b0d
   hashdiff (1.2.1) sha256=9c079dbc513dfc8833ab59c0c2d8f230fa28499cc5efb4b8dd276cf931457cd1
-  html2rss (0.30.0) sha256=a0ec169cf4a41954b2ec327625b15e81d718061a59a0bd27670ca01f238a2852
+  html2rss (0.30.0)
   html2rss-configs (0.2.0)
-  http-2 (1.2.2) sha256=81b5d45f50fd4cd5f8c5d09651184bec9401e3ef169c3eb3e5b003d5614a92b9
-  httpx (1.8.3) sha256=cb88f2285c4ef17164d803a640dc393d28722cba7f282ad0e7f9f926cd02dc47
+  http-2 (1.2.3) sha256=f4e3a7000e9a8ab97595f09eac44c6ec10a2aa438360758124df0ca5bcb280d4
+  httpx (1.8.4) sha256=1782ecde81eb4e961ad8735ec74a6fec8e60efeaa4592c6b2f55d72e19aaeca8
   i18n (1.15.2) sha256=00f9eb62412fe593b2a65a97daa75300d37abb8f7202ec748e94b6d46a9dd1b5
   io-console (0.9.2) sha256=efa74f891dd03c0939a931dfc6e74c2813d904763d456ea9762b0525e748db08
   io-endpoint (0.18.0) sha256=720d186bcd584e8ba490bfc91dab332cc3c5ffee848b5b03894555cb275151aa
@@ -452,7 +458,7 @@ CHECKSUMS
   localhost (1.8.0) sha256=df7ea825b4f64949c588c17efac86bc47ddc4460d723778abe933b71759b2701
   logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
   loofah (2.25.2) sha256=2007f746959ac65552456e04b433e83deb22759ab38c838b4445c70e43425918
-  mcp (1.5.0) sha256=6f97785fa6e069eb667aa3d50299851ea9aca904b4abe8306f156bb8fd9eaff0
+  mcp (1.5.1) sha256=883ddd0f59e5bf43805e300158c7ecc4b6a559d126d584d41bd241355545bedf
   mime-types (3.7.0) sha256=dcebf61c246f08e15a4de34e386ebe8233791e868564a470c3fe77c00eed5e56
   mime-types-data (3.2026.0701) sha256=cd8811e1fb89d836499ba0582368a10ee74cef929ba956d1d5ddca045e6a730f
   minitest (6.0.6) sha256=153ea36d1d987a62942382b61075745042a2b3123b1cd48f4c3675af9cc7d6f1
@@ -529,4 +535,4 @@ CHECKSUMS
   zeitwerk (2.8.3) sha256=2c85125a8467ce069e20123d1e709a08955c9d29c118c25b46b7b7fafdbb92e5
 
 BUNDLED WITH
-  4.0.9
+  4.0.3

From 71810b9fce506185acf7845ae15da7b1ae503c25 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sat, 19 Sep 2026 21:31:50 +0200
Subject: [PATCH 002/108] refactor(feeds): own token config expansion in one
 place

Preview and serve would otherwise build different configs. One expansion owner, with the old private builder deleted, keeps those paths identical.
---
 app/web/feeds/generator_input.rb              | 36 ++++++++++++
 app/web/feeds/source_resolver.rb              | 13 +----
 .../web/feeds/generator_input_spec.rb         | 57 +++++++++++++++++++
 3 files changed, 94 insertions(+), 12 deletions(-)
 create mode 100644 app/web/feeds/generator_input.rb
 create mode 100644 spec/html2rss/web/feeds/generator_input_spec.rb

diff --git a/app/web/feeds/generator_input.rb b/app/web/feeds/generator_input.rb
new file mode 100644
index 00000000..ef1b5912
--- /dev/null
+++ b/app/web/feeds/generator_input.rb
@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Html2rss
+  module Web
+    module Feeds
+      ##
+      # Single owner of token-feed config expansion.
+      #
+      # Serve and studio preview both call {.for_token} so a preview cannot
+      # diverge from the feed a reader later receives.
+      module GeneratorInput
+        class << self
+          ##
+          # Builds the generator config for a signed token feed.
+          #
+          # Selector fragments are accepted on the signature now so both call
+          # sites share one method; merging them is a later widening.
+          #
+          # @param url [String] channel URL bound to the token
+          # @param strategy [String, Symbol] resolved request strategy
+          # @param selectors [Object, nil] reserved until refined selectors are signed
+          # @return [Hash{Symbol=>Object}]
+          def for_token(url:, strategy:, selectors: nil)
+            raise ArgumentError, 'selector expansion is not available' unless selectors.nil?
+
+            LocalConfig.global.slice(:stylesheets, :headers).merge(
+              channel: { url: },
+              auto_source: {},
+              strategy: strategy.to_sym
+            )
+          end
+        end
+      end
+    end
+  end
+end
diff --git a/app/web/feeds/source_resolver.rb b/app/web/feeds/source_resolver.rb
index c96d185c..ec589712 100644
--- a/app/web/feeds/source_resolver.rb
+++ b/app/web/feeds/source_resolver.rb
@@ -63,7 +63,7 @@ def resolve_token(feed_request)
           # @param feed_token [Html2rss::Web::FeedToken]
           # @return [Html2rss::Web::Feeds::Contracts::ResolvedSource]
           def build_token_source(feed_request, feed_token)
-            generator_input = token_generator_input(feed_token.url, resolved_strategy(feed_token))
+            generator_input = GeneratorInput.for_token(url: feed_token.url, strategy: resolved_strategy(feed_token))
             resolved_source(
               source_kind: :token,
               cache_identity: token_cache_identity(feed_request.token),
@@ -139,17 +139,6 @@ def resolved_strategy(feed_token)
             strategy
           end
 
-          # @param url [String]
-          # @param strategy [String]
-          # @return [Hash{Symbol=>Object}]
-          def token_generator_input(url, strategy)
-            LocalConfig.global.slice(:stylesheets, :headers).merge(
-              channel: { url: },
-              auto_source: {},
-              strategy: strategy.to_sym
-            )
-          end
-
           # @return [String]
           def default_strategy_name
             configured = Html2rss::Config.default_strategy_name.to_s
diff --git a/spec/html2rss/web/feeds/generator_input_spec.rb b/spec/html2rss/web/feeds/generator_input_spec.rb
new file mode 100644
index 00000000..4cd6e3c6
--- /dev/null
+++ b/spec/html2rss/web/feeds/generator_input_spec.rb
@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Html2rss::Web::Feeds::GeneratorInput do
+  let(:url) { 'https://example.com/private' }
+  let(:global_config) do
+    {
+      stylesheets: ['/rss.xsl'],
+      headers: { 'User-Agent' => 'html2rss-web' },
+      ignored: 'not copied'
+    }
+  end
+
+  before do
+    allow(Html2rss::Web::LocalConfig).to receive(:global).and_return(global_config)
+  end
+
+  describe '.for_token' do
+    it 'reproduces the token generator hash when selectors are absent' do
+      expect(described_class.for_token(url:, strategy: 'default')).to eq(
+        stylesheets: ['/rss.xsl'],
+        headers: { 'User-Agent' => 'html2rss-web' },
+        channel: { url: },
+        auto_source: {},
+        strategy: :default
+      )
+    end
+
+    context 'when serve and preview expand the same token' do
+      let(:feed_token) do
+        instance_double(Html2rss::Web::FeedToken, username: 'admin', url:, strategy: 'default')
+      end
+      let(:feed_request) do
+        Html2rss::Web::Feeds::Contracts::Request.new(
+          target_kind: :token, feed_name: nil, token: 'public-token', params: {}
+        )
+      end
+
+      before do
+        allow(Html2rss::Web::Auth).to receive(:validate_and_decode_feed_token)
+          .with('public-token').and_return(feed_token)
+        allow(Html2rss::Web::AccountManager).to receive(:get_account_by_username)
+          .with('admin').and_return({ username: 'admin' })
+        allow(Html2rss::Web::UrlValidator).to receive(:url_allowed?)
+          .with({ username: 'admin' }, url).and_return(true)
+        allow(Html2rss::Web::Flags).to receive(:auto_source_enabled?).and_return(true)
+      end
+
+      it 'returns one config for both paths' do
+        served = Html2rss::Web::Feeds::SourceResolver.call(feed_request).generator_input
+
+        expect(served).to eq(described_class.for_token(url:, strategy: feed_token.strategy))
+      end
+    end
+  end
+end

From 4e1b1d0cf51550c1fcc502b20f9c3f4685b123a5 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sat, 19 Sep 2026 21:35:35 +0200
Subject: [PATCH 003/108] feat(frontend): add refine route with result and
 empty-extraction on-ramps

Refine is memory-bound: #/refine carries no token, and a visit with no in-memory URL recovers onto remounted #/create the same way an unmatched result does.
---
 frontend/src/__tests__/ResultDisplay.test.tsx | 118 ++++++++++++++++++
 frontend/src/__tests__/appRoute.test.ts       |  30 +++++
 frontend/src/__tests__/decideJourney.test.ts  |  37 ++++++
 frontend/src/components/App.tsx               |   6 +
 frontend/src/components/AppPanels.tsx         |  32 ++++-
 frontend/src/components/ConfigStudio.tsx      |  16 +++
 frontend/src/components/ResultDisplay.tsx     |  11 +-
 frontend/src/feed/decideJourney.ts            |   9 +-
 frontend/src/feed/useFeedFlow.ts              |  21 +++-
 frontend/src/journey/copy.ts                  |   3 +-
 frontend/src/routes/appRoute.ts               |  14 +++
 11 files changed, 287 insertions(+), 10 deletions(-)
 create mode 100644 frontend/src/components/ConfigStudio.tsx

diff --git a/frontend/src/__tests__/ResultDisplay.test.tsx b/frontend/src/__tests__/ResultDisplay.test.tsx
index 810e6692..29b27cc4 100644
--- a/frontend/src/__tests__/ResultDisplay.test.tsx
+++ b/frontend/src/__tests__/ResultDisplay.test.tsx
@@ -1,11 +1,14 @@
 import { describe, it, expect, beforeEach, vi } from 'vitest';
 import { render, screen, fireEvent, waitFor } from '@testing-library/preact';
 import { ResultDisplay } from '../components/ResultDisplay';
+import { CreateFeedPanel } from '../components/AppPanels';
 import { COPY } from '../journey/copy';
 import type { AppViewModel } from '../feed';
+import type { FeedCreationError } from '../api/contracts';
 
 describe('ResultDisplay', () => {
   const mockOnCreateAnother = vi.fn();
+  const mockOnRefine = vi.fn();
   const mockOnRetryPreview = vi.fn();
   const mockViewModel: Extract<AppViewModel, { kind: 'result' }> = {
     kind: 'result',
@@ -77,6 +80,7 @@ describe('ResultDisplay', () => {
       <ResultDisplay
         viewModel={viewModelWithMultiplePreviewItems}
         onCreateAnother={mockOnCreateAnother}
+        onRefine={mockOnRefine}
         onRetryPreview={mockOnRetryPreview}
       />
     );
@@ -106,6 +110,7 @@ describe('ResultDisplay', () => {
           preview: { status: 'preview_loading', items: [], isLoading: true },
         }}
         onCreateAnother={mockOnCreateAnother}
+        onRefine={mockOnRefine}
         onRetryPreview={mockOnRetryPreview}
       />
     );
@@ -132,6 +137,7 @@ describe('ResultDisplay', () => {
           ],
         }}
         onCreateAnother={mockOnCreateAnother}
+        onRefine={mockOnRefine}
         onRetryPreview={mockOnRetryPreview}
       />
     );
@@ -146,6 +152,7 @@ describe('ResultDisplay', () => {
       <ResultDisplay
         viewModel={mockViewModel}
         onCreateAnother={mockOnCreateAnother}
+        onRefine={mockOnRefine}
         onRetryPreview={mockOnRetryPreview}
       />
     );
@@ -164,6 +171,7 @@ describe('ResultDisplay', () => {
       <ResultDisplay
         viewModel={mockViewModel}
         onCreateAnother={mockOnCreateAnother}
+        onRefine={mockOnRefine}
         onRetryPreview={mockOnRetryPreview}
       />
     );
@@ -191,6 +199,7 @@ describe('ResultDisplay', () => {
           ],
         }}
         onCreateAnother={mockOnCreateAnother}
+        onRefine={mockOnRefine}
         onRetryPreview={mockOnRetryPreview}
       />
     );
@@ -217,6 +226,7 @@ describe('ResultDisplay', () => {
           ],
         }}
         onCreateAnother={mockOnCreateAnother}
+        onRefine={mockOnRefine}
         onRetryPreview={mockOnRetryPreview}
       />
     );
@@ -224,4 +234,112 @@ describe('ResultDisplay', () => {
     expect(screen.getByText('Feed fetching is temporarily unavailable.')).toBeInTheDocument();
     expect(screen.getByRole('button', { name: COPY.checkAgain })).toBeInTheDocument();
   });
+
+  it('offers a quiet refine action beside create another without taking copy focus', async () => {
+    render(
+      <ResultDisplay
+        viewModel={mockViewModel}
+        onCreateAnother={mockOnCreateAnother}
+        onRefine={mockOnRefine}
+        onRetryPreview={mockOnRetryPreview}
+      />
+    );
+
+    const refine = screen.getByRole('button', { name: COPY.refineSelectors });
+    const createAnother = screen.getByRole('button', { name: COPY.createAnother });
+    const copyFeedUrl = screen.getByRole('button', { name: COPY.copyFeedUrl });
+
+    expect(refine).toHaveClass('btn', 'btn--quiet', 'btn--linkish');
+    expect(refine.parentElement).toBe(createAnother.parentElement);
+    expect(refine.parentElement).toHaveClass('ui-actions');
+    await waitFor(() => {
+      expect(document.activeElement).toBe(copyFeedUrl);
+    });
+
+    fireEvent.click(refine);
+    expect(mockOnRefine).toHaveBeenCalledTimes(1);
+  });
+});
+
+function renderEmptyExtractionError(error: FeedCreationError, onRefine = vi.fn(), onRetryCreate = vi.fn()) {
+  const noop = vi.fn();
+  render(
+    <CreateFeedPanel
+      focusComposerKey={0}
+      viewModel={{
+        kind: 'error',
+        message: error.message,
+        error,
+        errorKind: error.kind,
+      }}
+      isCreating={false}
+      feedFormData={{ url: 'https://example.com/articles' }}
+      feedFieldErrors={{ url: '', form: '' }}
+      submitDisabled={false}
+      feedCreationEnabled
+      catalogEntries={[]}
+      featuredFeeds={[]}
+      tokenDraft=""
+      onFeedSubmit={noop}
+      onFeedFieldChange={noop}
+      onTokenDraftChange={noop}
+      onSaveToken={noop}
+      onCancelTokenPrompt={noop}
+      onRetryCreate={onRetryCreate}
+      onRefine={onRefine}
+    />
+  );
+
+  return { onRefine, onRetryCreate };
+}
+
+describe('empty extraction refine on-ramp', () => {
+  it('offers refine beside Try again only for an empty extraction', () => {
+    const { onRefine } = renderEmptyExtractionError({
+      kind: 'input',
+      code: 'EXTRACTION_EMPTY',
+      retryable: true,
+      nextAction: 'retry',
+      retryAction: 'primary',
+      message: 'We could not extract feed items from this page yet.',
+    });
+
+    const refine = screen.getByRole('button', { name: COPY.refineSelectors });
+    const tryAgain = screen.getByRole('button', { name: COPY.tryAgain });
+
+    expect(refine).toHaveClass('btn', 'btn--quiet', 'btn--linkish');
+    expect(refine.parentElement).toBe(tryAgain.parentElement);
+    expect(refine.parentElement).toHaveClass('notice__actions');
+
+    fireEvent.click(refine);
+    expect(onRefine).toHaveBeenCalledTimes(1);
+  });
+
+  it('offers refine without Try again when empty extraction is not retryable', () => {
+    renderEmptyExtractionError({
+      kind: 'input',
+      code: 'EXTRACTION_EMPTY',
+      retryable: false,
+      nextAction: 'correct_input',
+      retryAction: 'none',
+      message: 'We could not extract feed items from this page yet.',
+    });
+
+    expect(screen.getByRole('button', { name: COPY.refineSelectors })).toBeInTheDocument();
+    expect(screen.queryByRole('button', { name: COPY.tryAgain })).not.toBeInTheDocument();
+  });
+
+  it('does not offer refine for other create errors', () => {
+    renderEmptyExtractionError({
+      kind: 'input',
+      code: 'BLOCKED_SURFACE',
+      retryable: false,
+      nextAction: 'correct_input',
+      retryAction: 'none',
+      message: 'This site blocked automated access.',
+    });
+
+    expect(screen.queryByRole('button', { name: COPY.refineSelectors })).not.toBeInTheDocument();
+    expect(screen.queryByRole('button', { name: COPY.tryAgain })).not.toBeInTheDocument();
+  });
 });
diff --git a/frontend/src/__tests__/appRoute.test.ts b/frontend/src/__tests__/appRoute.test.ts
index 0f7c3b5f..a2cb2eca 100644
--- a/frontend/src/__tests__/appRoute.test.ts
+++ b/frontend/src/__tests__/appRoute.test.ts
@@ -88,4 +88,34 @@ describe('appRoute', () => {
     });
     unmount();
   });
+
+  it('reads refine without a token or prefill URL', () => {
+    expect(
+      readAppRoute({
+        pathname: '/',
+        search: '?url=https%3A%2F%2Fexample.com',
+        hash: '#/refine?url=https%3A%2F%2Fexample.com',
+      })
+    ).toEqual({ kind: 'refine' });
+
+    expect(
+      readAppRoute({
+        pathname: '/',
+        search: '',
+        hash: '#/refine/',
+      })
+    ).toEqual({ kind: 'refine' });
+
+    expect(buildAppRouteHref({ kind: 'refine' }, 'http://localhost/')).toBe('http://localhost/#/refine');
+  });
+
+  it('canonicalizes hashbang refine hashes to #/refine', () => {
+    history.replaceState({}, '', 'http://localhost:3000/#!/refine');
+
+    const { result, unmount } = renderHook(() => useAppRoute());
+
+    expect(location.hash).toBe('#/refine');
+    expect(result.current.route).toEqual({ kind: 'refine' });
+    unmount();
+  });
 });
diff --git a/frontend/src/__tests__/decideJourney.test.ts b/frontend/src/__tests__/decideJourney.test.ts
index 9e0ef9af..cd6b9afc 100644
--- a/frontend/src/__tests__/decideJourney.test.ts
+++ b/frontend/src/__tests__/decideJourney.test.ts
@@ -10,6 +10,7 @@ describe('decideJourney', () => {
         feedFieldErrors: emptyErrors,
         isCreating: false,
         route: { kind: 'create' },
+        sourceUrl: '',
         tokenError: '',
       })
     ).toEqual({ kind: 'create' });
@@ -20,6 +21,7 @@ describe('decideJourney', () => {
       feedFieldErrors: emptyErrors,
       isCreating: false,
       route: { kind: 'result', feedToken: 'token' },
+      sourceUrl: 'https://example.com',
       tokenError: '',
       result: {
         feed: {
@@ -49,6 +51,7 @@ describe('decideJourney', () => {
         feedFieldErrors: emptyErrors,
         isCreating: false,
         route: { kind: 'result', feedToken: 'route-token' },
+        sourceUrl: '',
         tokenError: '',
         result: {
           feed: {
@@ -72,6 +75,7 @@ describe('decideJourney', () => {
         feedFieldErrors: emptyErrors,
         isCreating: false,
         route: { kind: 'result', feedToken: 'route-token' },
+        sourceUrl: '',
         tokenError: '',
       })
     ).toEqual({ kind: 'create' });
@@ -83,6 +87,7 @@ describe('decideJourney', () => {
         feedFieldErrors: emptyErrors,
         isCreating: true,
         route: { kind: 'create' },
+        sourceUrl: '',
         tokenError: '',
       })
     ).toEqual({ kind: 'submitting' });
@@ -92,6 +97,7 @@ describe('decideJourney', () => {
         feedFieldErrors: { url: '', form: 'Bad url' },
         isCreating: false,
         route: { kind: 'create' },
+        sourceUrl: '',
         tokenError: '',
         creationError: {
           kind: 'input',
@@ -111,8 +117,39 @@ describe('decideJourney', () => {
         feedFieldErrors: emptyErrors,
         isCreating: true,
         route: { kind: 'token' },
+        sourceUrl: 'https://example.com',
         tokenError: '',
       })
     ).toEqual({ kind: 'token_prompt', tokenError: '' });
   });
+
+  it('keeps refine only while an in-memory URL exists', () => {
+    expect(
+      decideJourney({
+        feedFieldErrors: emptyErrors,
+        isCreating: false,
+        route: { kind: 'refine' },
+        sourceUrl: 'https://example.com/articles',
+        tokenError: '',
+        creationError: {
+          kind: 'input',
+          code: 'EXTRACTION_EMPTY',
+          retryable: false,
+          nextAction: 'correct_input',
+          retryAction: 'none',
+          message: 'Empty',
+        },
+      })
+    ).toEqual({ kind: 'refine' });
+
+    expect(
+      decideJourney({
+        feedFieldErrors: emptyErrors,
+        isCreating: false,
+        route: { kind: 'refine' },
+        sourceUrl: ' '.repeat(3),
+        tokenError: '',
+      })
+    ).toEqual({ kind: 'create' });
+  });
 });
diff --git a/frontend/src/components/App.tsx b/frontend/src/components/App.tsx
index daebf778..56b29e22 100644
--- a/frontend/src/components/App.tsx
+++ b/frontend/src/components/App.tsx
@@ -1,6 +1,7 @@
 import type { JSX } from 'preact';
 import { ResultDisplay } from './ResultDisplay';
 import { CreateFeedPanel, UtilityStrip } from './AppPanels';
+import { ConfigStudio } from './ConfigStudio';
 import { Notice } from './Notice';
 import { COPY } from '../journey/copy';
 import { useSession } from '../session';
@@ -62,6 +63,7 @@ export function App() {
     onCancelTokenPrompt,
     onRetryCreate,
     onCreateAnother,
+    onRefine,
     onRetryPreview,
     setBookmarkletNotice,
     setTokenDraft,
@@ -105,9 +107,12 @@ export function App() {
       <ResultDisplay
         viewModel={viewModel}
         onCreateAnother={onCreateAnother}
+        onRefine={onRefine}
         onRetryPreview={onRetryPreview}
       />
     );
+  } else if (viewModel.kind === 'refine') {
+    bodyContent = <ConfigStudio />;
   } else {
     bodyContent = (
       <CreateFeedPanel
@@ -127,6 +132,7 @@ export function App() {
         onSaveToken={onSaveToken}
         onCancelTokenPrompt={onCancelTokenPrompt}
         onRetryCreate={onRetryCreate}
+        onRefine={onRefine}
       />
     );
   }
diff --git a/frontend/src/components/AppPanels.tsx b/frontend/src/components/AppPanels.tsx
index be1963b8..94164e73 100644
--- a/frontend/src/components/AppPanels.tsx
+++ b/frontend/src/components/AppPanels.tsx
@@ -17,7 +17,7 @@ export interface FeedFieldErrors {
   form: string;
 }
 
-type CreatePanelViewModel = Exclude<AppViewModel, { kind: 'result' }>;
+type CreatePanelViewModel = Exclude<AppViewModel, { kind: 'result' } | { kind: 'refine' }>;
 
 interface CreateFeedPanelProperties {
   focusComposerKey: number;
@@ -36,6 +36,7 @@ interface CreateFeedPanelProperties {
   onSaveToken: () => void;
   onCancelTokenPrompt: () => void;
   onRetryCreate: () => void;
+  onRefine: () => void;
 }
 
 interface UrlEntrySectionProperties {
@@ -353,15 +354,21 @@ interface ActionFeedbackProperties {
   failureMessage: string;
   isCreating: boolean;
   isShowRetryButton: boolean;
+  shouldOfferRefine: boolean;
   onRetryCreate: () => void;
+  onRefine: () => void;
 }
 
 function ActionFeedback({
   failureMessage,
   isCreating,
   isShowRetryButton,
+  shouldOfferRefine,
   onRetryCreate,
+  onRefine,
 }: ActionFeedbackProperties) {
+  const hasActions = isShowRetryButton || shouldOfferRefine;
+
   return (
     <>
       {failureMessage && (
@@ -370,11 +377,20 @@ function ActionFeedback({
           tone="error"
           title={isShowRetryButton ? COPY.createFailedRetryTitle : COPY.createFailedTitle}
           actions={
-            isShowRetryButton && (
-              <button type="button" class="btn btn--primary" onClick={onRetryCreate}>
-                {COPY.tryAgain}
-              </button>
-            )
+            hasActions ? (
+              <>
+                {isShowRetryButton ? (
+                  <button type="button" class="btn btn--primary" onClick={onRetryCreate}>
+                    {COPY.tryAgain}
+                  </button>
+                ) : undefined}
+                {shouldOfferRefine ? (
+                  <button type="button" class="btn btn--quiet btn--linkish" onClick={onRefine}>
+                    {COPY.refineSelectors}
+                  </button>
+                ) : undefined}
+              </>
+            ) : undefined
           }
         >
           <p>{failureMessage}</p>
@@ -403,6 +419,7 @@ export function CreateFeedPanel({
   onSaveToken,
   onCancelTokenPrompt,
   onRetryCreate,
+  onRefine,
 }: CreateFeedPanelProperties) {
   const urlInputReference = useRef<HTMLInputElement>(null);
   const tokenInputReference = useRef<HTMLInputElement>(null);
@@ -422,6 +439,7 @@ export function CreateFeedPanel({
   const isShowRetryButton = Boolean(
     creationError && creationError.nextAction === 'retry' && creationError.retryAction !== 'none'
   );
+  const shouldOfferRefine = viewModel.kind === 'error' && creationError?.code === 'EXTRACTION_EMPTY';
   const isCreatingFeed = !isTokenPrompt && isSubmitting;
   const tokenCreating = isTokenPrompt && flowCreating;
 
@@ -493,7 +511,9 @@ export function CreateFeedPanel({
           failureMessage={failureMessage}
           isCreating={isCreatingFeed}
           isShowRetryButton={isShowRetryButton}
+          shouldOfferRefine={shouldOfferRefine}
           onRetryCreate={onRetryCreate}
+          onRefine={onRefine}
         />
       </div>
       {isTokenPrompt ? (
diff --git a/frontend/src/components/ConfigStudio.tsx b/frontend/src/components/ConfigStudio.tsx
new file mode 100644
index 00000000..42e95bec
--- /dev/null
+++ b/frontend/src/components/ConfigStudio.tsx
@@ -0,0 +1,16 @@
+import { COPY } from '../journey/copy';
+
+/** Empty refine shell. Selector controls land in a later phase. */
+export function ConfigStudio() {
+  return (
+    <section
+      class="ui-card ui-card--padded ui-card--framed"
+      data-state="refine"
+      aria-labelledby="refine-title"
+    >
+      <h1 id="refine-title" class="ui-display-title">
+        {COPY.refineSelectors}
+      </h1>
+    </section>
+  );
+}
diff --git a/frontend/src/components/ResultDisplay.tsx b/frontend/src/components/ResultDisplay.tsx
index 6045e390..6aa3237e 100644
--- a/frontend/src/components/ResultDisplay.tsx
+++ b/frontend/src/components/ResultDisplay.tsx
@@ -8,6 +8,7 @@ import { PreviewItem } from './PreviewItem';
 interface ResultDisplayProperties {
   viewModel: Extract<AppViewModel, { kind: 'result' }>;
   onCreateAnother: () => void;
+  onRefine: () => void;
   onRetryPreview: () => void;
 }
 
@@ -26,7 +27,12 @@ function PreviewSection({ ariaLabel, eyebrow, children }: PreviewSectionProperti
   );
 }
 
-export function ResultDisplay({ viewModel, onCreateAnother, onRetryPreview }: ResultDisplayProperties) {
+export function ResultDisplay({
+  viewModel,
+  onCreateAnother,
+  onRefine,
+  onRetryPreview,
+}: ResultDisplayProperties) {
   const [copied, setCopied] = useState(false);
   const copyResetReference = useRef<ReturnType<typeof globalThis.setTimeout> | undefined>(undefined);
   const copyButtonReference = useRef<HTMLButtonElement>(null);
@@ -96,6 +102,9 @@ export function ResultDisplay({ viewModel, onCreateAnother, onRetryPreview }: Re
             {COPY.openInFeedReader}
           </a>
         )}
+        <button type="button" class="btn btn--quiet btn--linkish" onClick={onRefine}>
+          {COPY.refineSelectors}
+        </button>
         <button type="button" class="btn btn--quiet btn--linkish" onClick={onCreateAnother}>
           {COPY.createAnother}
         </button>
diff --git a/frontend/src/feed/decideJourney.ts b/frontend/src/feed/decideJourney.ts
index 5c2fedff..9b63eefe 100644
--- a/frontend/src/feed/decideJourney.ts
+++ b/frontend/src/feed/decideJourney.ts
@@ -23,7 +23,8 @@ export type AppViewModel =
       message: string;
       error?: FeedCreationError;
       errorKind?: FeedCreationError['kind'];
-    };
+    }
+  | { kind: 'refine' };
 
 /**
  * Pure projection of journey kind from Feed Flow state.
@@ -35,6 +36,7 @@ export function decideJourney({
   feedFieldErrors,
   isCreating,
   route,
+  sourceUrl,
   tokenError,
   result,
 }: {
@@ -42,9 +44,14 @@ export function decideJourney({
   feedFieldErrors: { url: string; form: string };
   isCreating: boolean;
   route: AppRoute;
+  sourceUrl: string;
   tokenError: string;
   result?: CreatedFeedResult;
 }): AppViewModel {
+  if (route.kind === 'refine') {
+    return sourceUrl.trim() ? { kind: 'refine' } : { kind: 'create' };
+  }
+
   if (route.kind === 'result' && result && result.feed.feed_token === route.feedToken) {
     return {
       kind: 'result',
diff --git a/frontend/src/feed/useFeedFlow.ts b/frontend/src/feed/useFeedFlow.ts
index 3f0d3bb1..54e13f8d 100644
--- a/frontend/src/feed/useFeedFlow.ts
+++ b/frontend/src/feed/useFeedFlow.ts
@@ -57,7 +57,7 @@ export function useFeedFlow({
   const [bookmarkletNotice, setBookmarkletNotice] = useState('');
   const [focusCreateComposerKey, setFocusCreateComposerKey] = useState(0);
 
-  const routePrefillUrl = route.kind === 'result' ? undefined : route.prefillUrl;
+  const routePrefillUrl = route.kind === 'create' || route.kind === 'token' ? route.prefillUrl : undefined;
   const autoSubmitUrlReference = useRef<string | undefined>(routePrefillUrl);
   const hasAutoSubmittedReference = useRef(false);
   const previousRouteKindReference = useRef(route.kind);
@@ -202,6 +202,15 @@ export function useFeedFlow({
     navigate({ kind: 'create' }, { replace: true });
   }, [navigate, result, route]);
 
+  // Recover refine routes with no in-memory URL onto a remounted create view.
+  useEffect(() => {
+    if (route.kind !== 'refine') return;
+    if (inMemorySourceUrl(feedFormData.url, result?.feed.url)) return;
+
+    // Do not carry a prefill URL — that would re-trigger auto-submit.
+    navigate({ kind: 'create' }, { replace: true });
+  }, [feedFormData.url, navigate, result, route]);
+
   useEffect(() => {
     const previousKind = previousRouteKindReference.current;
     const previousCreateEntryKey = previousCreateEntryKeyReference.current;
@@ -236,6 +245,7 @@ export function useFeedFlow({
     feedFieldErrors,
     isCreating,
     route,
+    sourceUrl: inMemorySourceUrl(feedFormData.url, result?.feed.url),
     tokenError,
     result,
   });
@@ -275,9 +285,18 @@ export function useFeedFlow({
       setFocusCreateComposerKey((current) => current + 1);
       navigate({ kind: 'create', prefillUrl: feedFormData.url || undefined });
     },
+    onRefine: () => {
+      navigate({ kind: 'refine' });
+    },
     onRetryPreview: retryPreviewFetch,
     setBookmarkletNotice,
     setTokenDraft,
     setTokenError,
   };
 }
+
+function inMemorySourceUrl(formUrl: string, pageUrl: string | undefined): string {
+  const fromForm = formUrl.trim();
+  if (fromForm) return fromForm;
+  return pageUrl?.trim() ?? '';
+}
diff --git a/frontend/src/journey/copy.ts b/frontend/src/journey/copy.ts
index 7ebe49af..41bc3a5a 100644
--- a/frontend/src/journey/copy.ts
+++ b/frontend/src/journey/copy.ts
@@ -1,4 +1,4 @@
-/** Sole UI copy owner for create / token / result journey states. */
+/** Sole UI copy owner for create / token / result / refine journey states. */
 export const COPY = {
   creating: 'Creating feed',
   previewChecking: 'Checking preview',
@@ -40,6 +40,7 @@ export const COPY = {
   openJsonFeed: 'Open JSON Feed',
   openInFeedReader: 'Open in feed reader',
   createAnother: 'Create another feed',
+  refineSelectors: 'Refine selectors',
   createFeed: 'Create feed',
   saveAndContinue: 'Save and continue',
   back: 'Back',
diff --git a/frontend/src/routes/appRoute.ts b/frontend/src/routes/appRoute.ts
index 27ec38db..6d4daf8a 100644
--- a/frontend/src/routes/appRoute.ts
+++ b/frontend/src/routes/appRoute.ts
@@ -12,6 +12,9 @@ export type AppRoute =
   | {
       kind: 'result';
       feedToken: string;
+    }
+  | {
+      kind: 'refine';
     };
 
 interface RouteNavigationOptions {
@@ -27,6 +30,7 @@ interface RouteLocationLike {
 const ROUTE_PATHS = {
   create: '/create',
   token: '/token',
+  refine: '/refine',
   resultPrefix: '/result/',
 } as const;
 
@@ -43,6 +47,10 @@ export function readAppRoute(locationLike: RouteLocationLike = getCurrentLocatio
     return prefillUrl ? { kind: 'token', prefillUrl } : { kind: 'token' };
   }
 
+  if (pathname === ROUTE_PATHS.refine) {
+    return { kind: 'refine' };
+  }
+
   if (pathname.startsWith(ROUTE_PATHS.resultPrefix)) {
     const feedToken = pathname.slice(ROUTE_PATHS.resultPrefix.length);
     if (feedToken) return { kind: 'result', feedToken };
@@ -72,6 +80,12 @@ export function buildAppRouteHref(route: AppRoute, baseHref = getCurrentHref()):
     return url.href;
   }
 
+  if (route.kind === 'refine') {
+    url.hash = ROUTE_PATHS.refine;
+    url.search = '';
+    return url.href;
+  }
+
   url.hash = `${ROUTE_PATHS.resultPrefix}${route.feedToken}`;
   url.search = '';
   return url.href;

From 0e25d5b338012d354d411459d6cdde5b19d68950 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sat, 19 Sep 2026 21:41:00 +0200
Subject: [PATCH 004/108] feat(security): add refined-selectors allowlist for
 client-authored configs

Client config must not be able to rewrite channel.url or headers. One allowlist owns that rule and runs again when a token is decoded.
---
 app/web/security/refined_selectors.rb         | 156 ++++++++++++++++++
 .../web/security/refined_selectors_spec.rb    |  76 +++++++++
 2 files changed, 232 insertions(+)
 create mode 100644 app/web/security/refined_selectors.rb
 create mode 100644 spec/html2rss/web/security/refined_selectors_spec.rb

diff --git a/app/web/security/refined_selectors.rb b/app/web/security/refined_selectors.rb
new file mode 100644
index 00000000..00011c6a
--- /dev/null
+++ b/app/web/security/refined_selectors.rb
@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Html2rss
+  module Web
+    ##
+    # Allowlisted selector fragment a client may sign into a feed token.
+    #
+    # This is the only owner of which config keys may be client-authored.
+    # {.from_client} and {.from_wire} share one rule so a leaked signing
+    # secret cannot widen what decode will execute.
+    RefinedSelectors = Data.define(:selectors) do
+      ##
+      # @param selectors [Hash{Symbol=>Object}] allowlisted selectors subtree
+      # @return [Html2rss::Web::RefinedSelectors]
+      def initialize(selectors:)
+        super(selectors: deep_freeze(selectors))
+      end
+
+      ##
+      # Fragment merged into the token generator config. Never includes channel,
+      # headers, or any other client-controlled root key.
+      #
+      # @return [Hash{Symbol=>Object}]
+      def to_config_fragment = { selectors: }.freeze
+
+      ##
+      # Wire document stored under the token +c:+ key and covered by the signature.
+      #
+      # @return [Hash{Symbol=>Object}]
+      def to_wire = to_config_fragment
+
+      ##
+      # @return [Boolean]
+      def empty? = selectors.empty?
+
+      private
+
+      # @param value [Object]
+      # @return [Object]
+      def deep_freeze(value)
+        case value
+        in Hash then value.each_value { deep_freeze(it) }
+        in Array then value.each { deep_freeze(it) }
+        in String then return value.freeze
+        else return value
+        end
+        value.freeze
+      end
+    end
+
+    class RefinedSelectors
+      # Root keys a client fragment may contain. Published schema reads this set.
+      ALLOWED_KEYS = Set[:selectors].freeze
+      # Root keys rejected by name so the error is not a generic invalid-config.
+      DENIED_KEYS = Set[
+        :auto_source, :channel, :directory, :headers, :params, :registry, :request, :strategy, :stylesheets
+      ].freeze
+      # Keeps the signed token inside practical feed-URL lengths.
+      MAX_WIRE_BYTES = 2_048
+      # Placeholder channel used only so schema validation can judge the selectors subtree.
+      VALIDATION_CHANNEL_URL = 'https://example.com/'
+      private_constant :VALIDATION_CHANNEL_URL
+
+      class << self
+        ##
+        # Builds refined selectors from a client config fragment.
+        #
+        # @param hash [Hash] client object; only +selectors+ is permitted
+        # @return [Html2rss::Web::RefinedSelectors]
+        # @raise [Html2rss::Web::BadRequestError] when the fragment is not allowlisted
+        def from_client(hash) = build(hash)
+
+        ##
+        # Rebuilds refined selectors from a decoded token wire document.
+        #
+        # @param hash [Hash] wire object previously returned by {#to_wire}
+        # @return [Html2rss::Web::RefinedSelectors]
+        # @raise [Html2rss::Web::BadRequestError] when the fragment is not allowlisted
+        def from_wire(hash) = build(hash)
+
+        private
+
+        # @param hash [Object]
+        # @return [Html2rss::Web::RefinedSelectors]
+        def build(hash)
+          selectors = permitted_selectors(normalized_fragment(hash))
+          enforce_wire_limit!(selectors)
+          validate_shape!(selectors)
+          new(selectors:)
+        end
+
+        # @param hash [Object]
+        # @return [Hash{Symbol=>Object}]
+        def normalized_fragment(hash)
+          raise BadRequestError, 'refined selectors must be an object' unless hash.is_a?(Hash)
+
+          symbolize(hash)
+        end
+
+        # @param fragment [Hash{Symbol=>Object}]
+        # @return [Hash{Symbol=>Object}]
+        def permitted_selectors(fragment)
+          reject_keys!(fragment)
+          selectors = fragment[:selectors]
+          raise BadRequestError, 'selectors must be an object' unless selectors.is_a?(Hash)
+
+          selectors
+        end
+
+        # @param fragment [Hash{Symbol=>Object}]
+        # @return [void]
+        def reject_keys!(fragment)
+          denied = fragment.each_key.find { DENIED_KEYS.include?(it) }
+          raise BadRequestError, "#{denied} is not allowed" if denied
+
+          unknown = fragment.each_key.find { !ALLOWED_KEYS.include?(it) }
+          raise BadRequestError, "#{unknown} is not allowed" if unknown
+        end
+
+        # @param selectors [Hash{Symbol=>Object}]
+        # @return [void]
+        def enforce_wire_limit!(selectors)
+          return if JSON.generate({ selectors: }).bytesize <= MAX_WIRE_BYTES
+
+          raise BadRequestError, "refined selectors exceed #{MAX_WIRE_BYTES} bytes"
+        end
+
+        # @param selectors [Hash{Symbol=>Object}]
+        # @return [void]
+        def validate_shape!(selectors)
+          report = Html2rss::Config.validate({ channel: { url: VALIDATION_CHANNEL_URL }, selectors: })
+          return if report.success?
+
+          raise BadRequestError, report.to_s
+        end
+
+        # @param value [Object]
+        # @return [Object]
+        def symbolize(value)
+          case value
+          in Hash
+            value.to_h { |key, nested| [key.to_sym, symbolize(nested)] }
+          in Array
+            value.map { symbolize(it) }
+          in String
+            value.dup
+          else
+            value
+          end
+        end
+      end
+    end
+  end
+end
diff --git a/spec/html2rss/web/security/refined_selectors_spec.rb b/spec/html2rss/web/security/refined_selectors_spec.rb
new file mode 100644
index 00000000..29e4ba7f
--- /dev/null
+++ b/spec/html2rss/web/security/refined_selectors_spec.rb
@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Html2rss::Web::RefinedSelectors do # rubocop:disable RSpec/SpecFilePathFormat
+  let(:selectors) { { items: { selector: 'article', enhance: true } } }
+  let(:fragment) { { selectors: } }
+
+  describe '.from_client and .from_wire' do
+    it 'accepts an allowlisted selectors fragment and freezes the handoff', :aggregate_failures do
+      refined = described_class.from_client(fragment)
+
+      expect(refined.to_config_fragment).to eq(selectors:)
+      expect(refined.to_wire).to eq(refined.to_config_fragment)
+      expect(refined).not_to be_empty
+      expect { refined.selectors[:items][:selector] << 'x' }.to raise_error(FrozenError)
+      expect(described_class.from_wire(refined.to_wire)).to eq(refined)
+    end
+
+    it 'does not freeze the caller hash' do
+      raw = { 'selectors' => { 'items' => { 'selector' => +'article', 'enhance' => true } } }
+
+      described_class.from_client(raw)
+
+      expect { raw['selectors']['items']['selector'] << 'x' }.not_to raise_error
+    end
+
+    it 'accepts string keys' do
+      refined = described_class.from_client(
+        'selectors' => { 'items' => { 'selector' => 'article', 'enhance' => false } }
+      )
+
+      expect(refined.selectors).to eq(items: { selector: 'article', enhance: false })
+    end
+
+    described_class::DENIED_KEYS.each do |key|
+      it "rejects #{key} on mint and on decode", :aggregate_failures do
+        payload = fragment.merge(key => { 'url' => 'https://evil.example' })
+
+        expect { described_class.from_client(payload) }
+          .to raise_error(Html2rss::Web::BadRequestError, "#{key} is not allowed")
+        expect { described_class.from_wire(payload) }
+          .to raise_error(Html2rss::Web::BadRequestError, "#{key} is not allowed")
+      end
+    end
+
+    it 'rejects unknown root keys' do
+      expect { described_class.from_client(foo: 1) }
+        .to raise_error(Html2rss::Web::BadRequestError, 'foo is not allowed')
+    end
+
+    it 'rejects a non-object fragment' do
+      expect { described_class.from_wire('selectors') }
+        .to raise_error(Html2rss::Web::BadRequestError, 'refined selectors must be an object')
+    end
+
+    it 'rejects a non-object selectors value' do
+      expect { described_class.from_client(selectors: 'article') }
+        .to raise_error(Html2rss::Web::BadRequestError, 'selectors must be an object')
+    end
+
+    it 'rejects fragments over the wire byte cap' do
+      payload = { selectors: { items: { selector: 'a' * (described_class::MAX_WIRE_BYTES + 1) } } }
+
+      expect { described_class.from_client(payload) }.to raise_error(
+        Html2rss::Web::BadRequestError,
+        "refined selectors exceed #{described_class::MAX_WIRE_BYTES} bytes"
+      )
+    end
+
+    it 'delegates shape failures to config validation' do
+      expect { described_class.from_client(selectors: { items: { selector: '' } }) }
+        .to raise_error(Html2rss::Web::BadRequestError, /selectors\.items\.selector \[invalid_value\]/)
+    end
+  end
+end

From 133fce170281a123211a500970f8484434ed4be5 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sat, 19 Sep 2026 21:51:11 +0200
Subject: [PATCH 005/108] feat(security): sign refined selectors into feed
 tokens

The signature gains selectors only when a token carries them, so feed URLs already in the wild keep validating.
---
 app/web/security/auth.rb             |  4 +-
 app/web/security/feed_token.rb       | 72 +++++++++++++++++++++++-----
 spec/html2rss/web/feed_token_spec.rb | 62 +++++++++++++++++++++++-
 3 files changed, 123 insertions(+), 15 deletions(-)

diff --git a/app/web/security/auth.rb b/app/web/security/auth.rb
index 89e5cca6..4c4188c9 100644
--- a/app/web/security/auth.rb
+++ b/app/web/security/auth.rb
@@ -25,13 +25,15 @@ def authenticate(request)
         # @param username [String]
         # @param url [String]
         # @param strategy [String, nil]
+        # @param selectors [Html2rss::Web::RefinedSelectors, nil]
         # @param expires_in [Integer] seconds (default: 10 years)
         # @return [String, nil] signed feed token when generation succeeds.
-        def generate_feed_token(username, url, strategy: nil, expires_in: FeedToken::DEFAULT_EXPIRY)
+        def generate_feed_token(username, url, strategy: nil, selectors: nil, expires_in: FeedToken::DEFAULT_EXPIRY)
           token = FeedToken::Signer.create(
             username: username,
             url: url,
             strategy: strategy,
+            selectors: selectors,
             expires_in: expires_in,
             secret_key: secret_key
           )
diff --git a/app/web/security/feed_token.rb b/app/web/security/feed_token.rb
index 37505d1e..2e947c6e 100644
--- a/app/web/security/feed_token.rb
+++ b/app/web/security/feed_token.rb
@@ -12,7 +12,20 @@ module Web
     #
     # Wire encoding and signature verification are unified inside this class to
     # keep the token lifetime concerns cohesive.
-    FeedToken = Data.define(:username, :url, :expires_at, :signature, :strategy) do
+    FeedToken = Data.define(:username, :url, :expires_at, :signature, :strategy, :selectors) do
+      ##
+      # @param username [String]
+      # @param url [String]
+      # @param expires_at [Integer]
+      # @param signature [String]
+      # @param strategy [String, nil]
+      # @param selectors [Html2rss::Web::RefinedSelectors, nil]
+      # @return [Html2rss::Web::FeedToken]
+      # rubocop:disable-next Metrics/ParameterLists
+      def initialize(username:, url:, expires_at:, signature:, strategy:, selectors: nil)
+        super
+      end
+
       # @return [Boolean]
       def expired?
         Time.now.to_i > expires_at
@@ -48,7 +61,7 @@ def decode(encoded_token)
             return unless valid_token_data?(token_data)
 
             decoded_token(token_data)
-          rescue JSON::ParserError, ArgumentError, Zlib::DataError, Zlib::BufError
+          rescue JSON::ParserError, ArgumentError, Zlib::DataError, Zlib::BufError, BadRequestError
             nil
           end
 
@@ -59,6 +72,7 @@ def decode(encoded_token)
           def wire_document(token)
             payload = { u: token.username, l: token.url, e: token.expires_at }
             payload[:t] = token.strategy if token.strategy
+            payload[:c] = token.selectors.to_wire if signable_selectors?(token.selectors)
             { p: payload, s: token.signature }
           end
 
@@ -78,10 +92,17 @@ def decoded_token(token_data)
               url: payload[:l],
               expires_at: payload[:e],
               signature: token_data[:s],
-              strategy: payload[:t]
+              strategy: payload[:t],
+              selectors: selectors_from_wire(payload[:c])
             )
           end
 
+          # @param wire [Object]
+          # @return [Boolean]
+          def valid_selectors_wire?(wire)
+            wire.nil? || wire.is_a?(Hash)
+          end
+
           # @param token_data [Object]
           # @return [Boolean]
           def valid_token_data?(token_data)
@@ -91,6 +112,20 @@ def valid_token_data?(token_data)
             signature.is_a?(String) && !signature.empty? && valid_payload?(token_data[:p])
           end
 
+          # @param wire [Hash, nil]
+          # @return [Html2rss::Web::RefinedSelectors, nil]
+          def selectors_from_wire(wire)
+            return if wire.nil?
+
+            RefinedSelectors.from_wire(wire)
+          end
+
+          # @param selectors [Html2rss::Web::RefinedSelectors, nil]
+          # @return [Boolean]
+          def signable_selectors?(selectors)
+            !selectors.nil? && !selectors.empty?
+          end
+
           # @param payload [Object]
           # @return [Boolean]
           def valid_payload?(payload)
@@ -98,7 +133,8 @@ def valid_payload?(payload)
               payload[:u].is_a?(String) &&
               payload[:l].is_a?(String) &&
               payload[:e].is_a?(Integer) &&
-              (payload[:t].nil? || payload[:t].is_a?(String))
+              (payload[:t].nil? || payload[:t].is_a?(String)) &&
+              valid_selectors_wire?(payload[:c])
           end
         end
       end
@@ -113,14 +149,16 @@ class << self
           # @param url [String]
           # @param secret_key [String]
           # @param strategy [String, nil]
+          # @param selectors [Html2rss::Web::RefinedSelectors, nil]
           # @param expires_in [Integer]
           # @return [Html2rss::Web::FeedToken, nil]
-          def create(username:, url:, secret_key:, strategy: nil, expires_in: DEFAULT_EXPIRY)
-            return unless valid_inputs?(username, url, secret_key, strategy)
+          # rubocop:disable-next Metrics/ParameterLists
+          def create(username:, url:, secret_key:, strategy: nil, selectors: nil, expires_in: DEFAULT_EXPIRY)
+            return unless valid_inputs?(username, url, secret_key, strategy, selectors)
 
             expires_at = Time.now.to_i + expires_in.to_i
-            signature = sign(secret_key, signature_payload(username, url, expires_at, strategy))
-            FeedToken.new(username:, url:, expires_at:, signature:, strategy:)
+            signature = sign(secret_key, signature_payload(username, url, expires_at, strategy, selectors))
+            FeedToken.new(username:, url:, expires_at:, signature:, strategy:, selectors:)
           end
 
           # @param encoded_token [String, nil]
@@ -153,7 +191,8 @@ def valid_signature?(token, secret_key)
             return false unless secret_key.is_a?(String) && !secret_key.empty?
 
             expected_signature = sign(secret_key, signature_payload(
-                                                    token.username, token.url, token.expires_at, token.strategy
+                                                    token.username, token.url, token.expires_at,
+                                                    token.strategy, token.selectors
                                                   ))
             signatures_match?(token.signature, expected_signature)
           end
@@ -164,10 +203,12 @@ def valid_signature?(token, secret_key)
           # @param url [String]
           # @param expires_at [Integer]
           # @param strategy [String, nil]
+          # @param selectors [Html2rss::Web::RefinedSelectors, nil]
           # @return [Hash{Symbol=>Object}]
-          def signature_payload(username, url, expires_at, strategy)
+          def signature_payload(username, url, expires_at, strategy, selectors = nil)
             payload = { username:, url:, expires_at: }
             payload[:strategy] = strategy if strategy
+            payload[:selectors] = selectors.to_wire if selectors && !selectors.empty?
             payload
           end
 
@@ -192,10 +233,11 @@ def signatures_match?(first, second)
           # @param url [Object]
           # @param secret_key [Object]
           # @param strategy [Object]
+          # @param selectors [Object]
           # @return [Boolean]
-          def valid_inputs?(username, url, secret_key, strategy)
+          def valid_inputs?(username, url, secret_key, strategy, selectors = nil)
             valid_username?(username) && UrlValidator.valid_url?(url) && valid_secret_key?(secret_key) &&
-              valid_strategy?(strategy)
+              valid_strategy?(strategy) && valid_selectors?(selectors)
           end
 
           # @param username [Object]
@@ -218,6 +260,12 @@ def valid_strategy?(strategy)
 
             strategy.is_a?(String) && !strategy.empty? && strategy.length <= 50 && strategy.match?(/\A[a-z0-9_]+\z/)
           end
+
+          # @param selectors [Object]
+          # @return [Boolean]
+          def valid_selectors?(selectors)
+            selectors.nil? || selectors.is_a?(RefinedSelectors)
+          end
         end
       end
     end
diff --git a/spec/html2rss/web/feed_token_spec.rb b/spec/html2rss/web/feed_token_spec.rb
index 3059af41..4efff54f 100644
--- a/spec/html2rss/web/feed_token_spec.rb
+++ b/spec/html2rss/web/feed_token_spec.rb
@@ -171,6 +171,21 @@
         expect(described_class.decode(nil)).to be_nil
       end
 
+      it 'rejects a selectors wire key that is not an object' do
+        bad_token = Base64.urlsafe_encode64(Zlib::Deflate.deflate({
+          p: { u: 'alice', l: 'https://example.com/feed', e: 123, c: 'nope' }, s: 'sig'
+        }.to_json))
+
+        expect(described_class.decode(bad_token)).to be_nil
+      end
+
+      it 'rejects selector wire outside the allowlist' do
+        wire = { u: 'alice', l: 'https://example.com/feed', e: 123, c: { channel: { url: 'https://evil.example' } } }
+        bad_token = Base64.urlsafe_encode64(Zlib::Deflate.deflate({ p: wire, s: 'sig' }.to_json))
+
+        expect(described_class.decode(bad_token)).to be_nil
+      end
+
       it 'rejects payloads with incorrect types', :aggregate_failures do
         invalid_payloads = [
           { u: 'alice', l: 'https://example.com/feed', e: '123456' },
@@ -203,15 +218,58 @@
     end
   end
 
+  describe 'refined selectors' do
+    let(:secret_key) { 'test-secret' }
+    let(:url) { 'https://example.com/feed' }
+    let(:selectors) do
+      Html2rss::Web::RefinedSelectors.from_client(selectors: { items: { selector: 'article', enhance: true } })
+    end
+
+    it 'keeps the legacy signature when selectors are absent' do
+      token = Html2rss::Web::FeedToken::Signer.create(username: 'alice', url:, secret_key:, strategy: 'some_strategy')
+      legacy = { username: 'alice', url:, expires_at: token.expires_at, strategy: 'some_strategy' }
+      digest = OpenSSL::HMAC.hexdigest('SHA256', secret_key, JSON.generate(legacy))
+
+      expect(token.signature).to eq(digest)
+    end
+
+    it 'round-trips signed selectors and rejects a swap', :aggregate_failures do
+      token = Html2rss::Web::FeedToken::Signer.create(
+        username: 'alice', url:, secret_key:, strategy: 'some_strategy', selectors:
+      )
+      encoded = Html2rss::Web::FeedToken::Codec.encode(token)
+      swapped = Html2rss::Web::RefinedSelectors.from_client(selectors: { items: { selector: 'section' } })
+      tampered = Html2rss::Web::FeedToken::Codec.encode(token.with(selectors: swapped))
+
+      expect(Html2rss::Web::FeedToken::Signer.validate(encoded, url, secret_key).selectors).to eq(selectors)
+      expect(Html2rss::Web::FeedToken::Signer.validate(tampered, url, secret_key)).to be_nil
+    end
+
+    it 'signs selectors passed through Auth.generate_feed_token' do
+      encoded = Html2rss::Web::Auth.generate_feed_token('admin', url, selectors:)
+
+      expect(Html2rss::Web::Auth.validate_and_decode_feed_token(encoded).selectors).to eq(selectors)
+    end
+  end
+
   describe '#expired?' do
     it 'returns true for past timestamps' do
-      token = described_class.new('alice', 'https://example.com/feed', Time.now.to_i - 1, 'sig', nil)
+      token = described_class.new(
+        username: 'alice',
+        url: 'https://example.com/feed',
+        expires_at: Time.now.to_i - 1,
+        signature: 'sig',
+        strategy: nil
+      )
 
       expect(token.expired?).to be(true)
     end
 
     it 'returns false for future timestamps' do
-      token = described_class.new('alice', 'https://example.com/feed', Time.now.to_i + 3600, 'sig', nil)
+      token = described_class.new(
+        username: 'alice', url: 'https://example.com/feed', expires_at: Time.now.to_i + 3600, signature: 'sig',
+        strategy: nil
+      )
 
       expect(token.expired?).to be(false)
     end

From ac850c8d1b530a9082efb5f7af93bfb9576069f2 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sat, 19 Sep 2026 22:05:35 +0200
Subject: [PATCH 006/108] feat(feeds): resolve token feeds with signed refined
 selectors

The served feed now expands the same signed selectors preview will use, and the allowlist runs again at serve time so a decoded token cannot skip it.
---
 app/web/feeds/generator_input.rb              | 12 ++++----
 app/web/feeds/source_resolver.rb              | 13 ++++++++-
 spec/html2rss/web/app_integration_spec.rb     |  3 +-
 .../web/feeds/generator_input_spec.rb         | 22 +++++++++++++-
 .../web/feeds/source_resolver_spec.rb         | 29 ++++++++++++++++++-
 5 files changed, 68 insertions(+), 11 deletions(-)

diff --git a/app/web/feeds/generator_input.rb b/app/web/feeds/generator_input.rb
index ef1b5912..8b393966 100644
--- a/app/web/feeds/generator_input.rb
+++ b/app/web/feeds/generator_input.rb
@@ -13,21 +13,19 @@ class << self
           ##
           # Builds the generator config for a signed token feed.
           #
-          # Selector fragments are accepted on the signature now so both call
-          # sites share one method; merging them is a later widening.
-          #
           # @param url [String] channel URL bound to the token
           # @param strategy [String, Symbol] resolved request strategy
-          # @param selectors [Object, nil] reserved until refined selectors are signed
+          # @param selectors [Html2rss::Web::RefinedSelectors, nil] signed selector fragment
           # @return [Hash{Symbol=>Object}]
           def for_token(url:, strategy:, selectors: nil)
-            raise ArgumentError, 'selector expansion is not available' unless selectors.nil?
-
-            LocalConfig.global.slice(:stylesheets, :headers).merge(
+            expanded = LocalConfig.global.slice(:stylesheets, :headers).merge(
               channel: { url: },
               auto_source: {},
               strategy: strategy.to_sym
             )
+            return expanded if selectors.nil? || selectors.empty?
+
+            expanded.merge(selectors.to_config_fragment)
           end
         end
       end
diff --git a/app/web/feeds/source_resolver.rb b/app/web/feeds/source_resolver.rb
index ec589712..9b55fb3e 100644
--- a/app/web/feeds/source_resolver.rb
+++ b/app/web/feeds/source_resolver.rb
@@ -63,7 +63,7 @@ def resolve_token(feed_request)
           # @param feed_token [Html2rss::Web::FeedToken]
           # @return [Html2rss::Web::Feeds::Contracts::ResolvedSource]
           def build_token_source(feed_request, feed_token)
-            generator_input = GeneratorInput.for_token(url: feed_token.url, strategy: resolved_strategy(feed_token))
+            generator_input = expanded_generator_input(feed_token)
             resolved_source(
               source_kind: :token,
               cache_identity: token_cache_identity(feed_request.token),
@@ -75,6 +75,17 @@ def build_token_source(feed_request, feed_token)
             )
           end
 
+          # @param feed_token [Html2rss::Web::FeedToken]
+          # @return [Hash{Symbol=>Object}]
+          def expanded_generator_input(feed_token)
+            selectors = feed_token.selectors
+            GeneratorInput.for_token(
+              url: feed_token.url,
+              strategy: resolved_strategy(feed_token),
+              selectors: selectors.nil? ? nil : RefinedSelectors.from_wire(selectors.to_wire)
+            )
+          end
+
           # @param kwargs [Hash{Symbol=>Object}]
           # @return [Html2rss::Web::Feeds::Contracts::ResolvedSource]
           def resolved_source(**kwargs)
diff --git a/spec/html2rss/web/app_integration_spec.rb b/spec/html2rss/web/app_integration_spec.rb
index 8d171710..508154f9 100644
--- a/spec/html2rss/web/app_integration_spec.rb
+++ b/spec/html2rss/web/app_integration_spec.rb
@@ -231,7 +231,8 @@ def stub_escaped_feed_token(raw_token:, encoded_token:)
         Html2rss::Web::FeedToken,
         url: feed_url,
         username: account[:username],
-        strategy: 'default'
+        strategy: 'default',
+        selectors: nil
       )
 
       allow(Html2rss::Web::FeedToken::Codec).to receive(:decode).with(raw_token).and_return(escaped_token_payload)
diff --git a/spec/html2rss/web/feeds/generator_input_spec.rb b/spec/html2rss/web/feeds/generator_input_spec.rb
index 4cd6e3c6..381ae3a7 100644
--- a/spec/html2rss/web/feeds/generator_input_spec.rb
+++ b/spec/html2rss/web/feeds/generator_input_spec.rb
@@ -27,9 +27,21 @@
       )
     end
 
+    it 'merges signed selectors without replacing the token url' do
+      selectors = Html2rss::Web::RefinedSelectors.from_client(
+        selectors: { items: { selector: 'article', enhance: true } }
+      )
+
+      expect(described_class.for_token(url:, strategy: 'default', selectors:)).to include(
+        channel: { url: },
+        strategy: :default,
+        selectors: { items: { selector: 'article', enhance: true } }
+      )
+    end
+
     context 'when serve and preview expand the same token' do
       let(:feed_token) do
-        instance_double(Html2rss::Web::FeedToken, username: 'admin', url:, strategy: 'default')
+        instance_double(Html2rss::Web::FeedToken, username: 'admin', url:, strategy: 'default', selectors: nil)
       end
       let(:feed_request) do
         Html2rss::Web::Feeds::Contracts::Request.new(
@@ -52,6 +64,14 @@
 
         expect(served).to eq(described_class.for_token(url:, strategy: feed_token.strategy))
       end
+
+      it 'returns one config when both paths carry the same selectors' do
+        selectors = Html2rss::Web::RefinedSelectors.from_client(selectors: { items: { selector: 'article' } })
+        allow(feed_token).to receive(:selectors).and_return(selectors)
+        served = Html2rss::Web::Feeds::SourceResolver.call(feed_request).generator_input
+
+        expect(served).to eq(described_class.for_token(url:, strategy: feed_token.strategy, selectors:))
+      end
     end
   end
 end
diff --git a/spec/html2rss/web/feeds/source_resolver_spec.rb b/spec/html2rss/web/feeds/source_resolver_spec.rb
index d30d882c..e777f3ee 100644
--- a/spec/html2rss/web/feeds/source_resolver_spec.rb
+++ b/spec/html2rss/web/feeds/source_resolver_spec.rb
@@ -89,7 +89,8 @@ def resolved_tuple(resolved)
           Html2rss::Web::FeedToken,
           username: 'admin',
           url: 'https://example.com/private',
-          strategy: 'default'
+          strategy: 'default',
+          selectors: nil
         )
       end
 
@@ -175,6 +176,32 @@ def resolved_tuple(resolved)
         expect { described_class.call(feed_request) }
           .to raise_error(Html2rss::Web::ForbiddenError, 'Access Denied')
       end
+
+      it 're-checks selector wire before building the generator config' do
+        allow(feed_token).to receive(:selectors).and_return(
+          instance_double(
+            Html2rss::Web::RefinedSelectors,
+            to_wire: { channel: { url: 'https://evil.example' } }
+          )
+        )
+
+        expect { described_class.call(feed_request) }
+          .to raise_error(Html2rss::Web::BadRequestError, 'channel is not allowed')
+      end
+
+      it 'keeps the token url when selectors are signed' do
+        selectors = Html2rss::Web::RefinedSelectors.from_client(
+          selectors: { items: { selector: 'article' } }
+        )
+        allow(feed_token).to receive(:selectors).and_return(selectors)
+
+        resolved = described_class.call(feed_request)
+
+        expect(resolved.generator_input).to include(
+          channel: { url: 'https://example.com/private' },
+          selectors: { items: { selector: 'article' } }
+        )
+      end
     end
   end
 end

From fa02d60cd92a80c0ba4089e577001b68f4540772 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sat, 19 Sep 2026 22:13:52 +0200
Subject: [PATCH 007/108] feat(api): add studio validate, preview, and suggest
 endpoints

Studio edits stay server-authoritative: validate reports schema issues without minting a token, preview selects Test::Result fields so the RSS body never leaves the server, and suggest returns one capture-derived selector with its evidence.
---
 app/web/api/v1/preview_feed.rb          | 116 +++++++++++++++++++
 app/web/api/v1/suggest_selectors.rb     | 113 ++++++++++++++++++
 app/web/api/v1/validate_config.rb       | 109 ++++++++++++++++++
 app/web/config/flags.rb                 |  14 ++-
 app/web/routes/api_v1/feed_routes.rb    |  35 ++++--
 frontend/src/api/generated/index.ts     |   4 +-
 frontend/src/api/generated/sdk.gen.ts   |  17 ++-
 frontend/src/api/generated/types.gen.ts |  69 +++++++++++
 public/openapi.yaml                     | 146 ++++++++++++++++++++++++
 spec/html2rss/web/api/v1_spec.rb        | 105 +++++++++++++++++
 10 files changed, 717 insertions(+), 11 deletions(-)
 create mode 100644 app/web/api/v1/preview_feed.rb
 create mode 100644 app/web/api/v1/suggest_selectors.rb
 create mode 100644 app/web/api/v1/validate_config.rb

diff --git a/app/web/api/v1/preview_feed.rb b/app/web/api/v1/preview_feed.rb
new file mode 100644
index 00000000..30cf07d4
--- /dev/null
+++ b/app/web/api/v1/preview_feed.rb
@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Html2rss
+  module Web
+    module Api
+      module V1
+        ##
+        # Live extraction preview for a refined token config.
+        #
+        # Builds the config through {Feeds::GeneratorInput} and selects
+        # {Html2rss::Test::Result} fields. Never forwards +#to_h+, which includes +rss:+.
+        module PreviewFeed
+          class << self
+            ##
+            # @param request [Rack::Request]
+            # @return [Hash{Symbol=>Object}]
+            def call(request)
+              account = live_account(request)
+              body = json_object(request)
+              url = allowed_url(body['url'], account)
+              result = Html2rss.test(preview_config(url, body['selectors']), min_items: 1)
+              Response.success(response: request.response, data: preview_fields(result))
+            end
+
+            private
+
+            # @param request [Rack::Request]
+            # @return [Hash]
+            def live_account(request)
+              raise ForbiddenError, 'Studio is disabled' unless Flags.studio_enabled?
+              raise AutoSourceDisabledError unless Flags.auto_source_enabled?
+
+              account = Auth.authenticate(request)
+              raise UnauthorizedError, 'Authentication required' unless account
+
+              account
+            end
+
+            # @param request [Rack::Request]
+            # @return [Hash]
+            def json_object(request)
+              raw = read_body(request)
+              return {} if raw.strip.empty?
+
+              parsed = JSON.parse(raw)
+              raise BadRequestError, 'Invalid JSON payload' unless parsed.is_a?(Hash)
+
+              parsed
+            rescue JSON::ParserError
+              raise BadRequestError, 'Invalid JSON payload'
+            end
+
+            def read_body(request)
+              limit = CreateFeed::MAX_BODY_BYTES
+              raise BadRequestError, 'Payload too large' if request.content_length.to_i > limit
+
+              request.body.read(limit + 1).to_s.tap do |raw|
+                request.body.rewind
+                raise BadRequestError, 'Payload too large' if raw.bytesize > limit
+              end
+            end
+
+            # @param raw_url [String, nil]
+            # @param account [Hash]
+            # @return [String]
+            def allowed_url(raw_url, account)
+              url = UrlValidator.canonical_url(raw_url.to_s.strip)
+              raise BadRequestError, 'URL parameter is required' if raw_url.to_s.strip.empty?
+              raise BadRequestError, 'Invalid URL format' unless url
+              raise ForbiddenError, 'URL not allowed for this account' unless UrlValidator.url_allowed?(account, url)
+
+              url
+            end
+
+            # @param url [String]
+            # @param selectors [Object]
+            # @return [Hash{Symbol=>Object}]
+            def preview_config(url, selectors)
+              Feeds::GeneratorInput.for_token(url:, strategy: default_strategy, selectors: refined(selectors))
+            end
+
+            # @param selectors [Object]
+            # @return [Html2rss::Web::RefinedSelectors, nil]
+            def refined(selectors)
+              return if selectors.nil?
+
+              RefinedSelectors.from_client({ selectors: })
+            end
+
+            # @return [String]
+            def default_strategy
+              configured = Html2rss::Config.default_strategy_name.to_s
+              configured.strip.empty? ? 'auto' : configured
+            end
+
+            # Selected fields only. {Html2rss::Test::Result#to_h} also carries +rss+.
+            #
+            # @param result [Html2rss::Test::Result]
+            # @return [Hash{Symbol=>Object}]
+            def preview_fields(result)
+              {
+                item_count: result.item_count,
+                sample_items: result.sample_items,
+                quality_report: result.quality_report&.to_h,
+                failure_kind: result.failure_kind&.to_sym,
+                validation_issues: result.validation_issues&.map(&:to_h)
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end
diff --git a/app/web/api/v1/suggest_selectors.rb b/app/web/api/v1/suggest_selectors.rb
new file mode 100644
index 00000000..219ef42a
--- /dev/null
+++ b/app/web/api/v1/suggest_selectors.rb
@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Html2rss
+  module Web
+    module Api
+      module V1
+        ##
+        # One capture-derived items selector for the refinement studio.
+        #
+        # +Html2rss.capture+ returns the first segment strategy that clears its
+        # quality gate, not a candidate list.
+        module SuggestSelectors
+          class << self
+            ##
+            # @param request [Rack::Request]
+            # @return [Hash{Symbol=>Object}]
+            def call(request)
+              account = live_account(request)
+              body = json_object(request)
+              captured = Html2rss.capture(
+                allowed_url(body['url'], account),
+                strategy: :auto,
+                items_selector: hint(body['items_selector'])
+              )
+              Response.success(response: request.response, data: suggestion(captured))
+            end
+
+            private
+
+            # @param request [Rack::Request]
+            # @return [Hash]
+            def live_account(request)
+              raise ForbiddenError, 'Studio is disabled' unless Flags.studio_enabled?
+              raise AutoSourceDisabledError unless Flags.auto_source_enabled?
+
+              account = Auth.authenticate(request)
+              raise UnauthorizedError, 'Authentication required' unless account
+
+              account
+            end
+
+            # @param request [Rack::Request]
+            # @return [Hash]
+            def json_object(request)
+              raw = read_body(request)
+              return {} if raw.strip.empty?
+
+              parsed = JSON.parse(raw)
+              raise BadRequestError, 'Invalid JSON payload' unless parsed.is_a?(Hash)
+
+              parsed
+            rescue JSON::ParserError
+              raise BadRequestError, 'Invalid JSON payload'
+            end
+
+            def read_body(request)
+              limit = CreateFeed::MAX_BODY_BYTES
+              raise BadRequestError, 'Payload too large' if request.content_length.to_i > limit
+
+              request.body.read(limit + 1).to_s.tap do |raw|
+                request.body.rewind
+                raise BadRequestError, 'Payload too large' if raw.bytesize > limit
+              end
+            end
+
+            # @param raw_url [String, nil]
+            # @param account [Hash]
+            # @return [String]
+            def allowed_url(raw_url, account)
+              url = UrlValidator.canonical_url(raw_url.to_s.strip)
+              raise BadRequestError, 'URL parameter is required' if raw_url.to_s.strip.empty?
+              raise BadRequestError, 'Invalid URL format' unless url
+              raise ForbiddenError, 'URL not allowed for this account' unless UrlValidator.url_allowed?(account, url)
+
+              url
+            end
+
+            # @param raw [Object]
+            # @return [String, nil]
+            def hint(raw)
+              text = raw.to_s.strip
+              text.empty? ? nil : text
+            end
+
+            # @param captured [Html2rss::Capture::CaptureResult]
+            # @return [Hash{Symbol=>Object}]
+            def suggestion(captured)
+              selectors = captured.config[:selectors] || captured.config['selectors']
+              items = selectors.is_a?(Hash) ? selectors[:items] || selectors['items'] : nil
+              {
+                selectors:,
+                segment_strategy: captured.segment_strategy&.to_s,
+                admission_drops: captured.admission_drops,
+                enhance: enhance_flag(items)
+              }
+            end
+
+            # @param items [Hash, nil]
+            # @return [Boolean, nil]
+            def enhance_flag(items)
+              return unless items.is_a?(Hash)
+              return items[:enhance] if items.key?(:enhance)
+
+              items['enhance'] if items.key?('enhance')
+            end
+          end
+        end
+      end
+    end
+  end
+end
diff --git a/app/web/api/v1/validate_config.rb b/app/web/api/v1/validate_config.rb
new file mode 100644
index 00000000..c932c371
--- /dev/null
+++ b/app/web/api/v1/validate_config.rb
@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Html2rss
+  module Web
+    module Api
+      module V1
+        ##
+        # Server-authoritative config check for the refinement studio.
+        #
+        # Parses YAML or a selectors object, gates it through {RefinedSelectors},
+        # and returns the gem validation report plus normalized YAML.
+        module ValidateConfig
+          PLACEHOLDER_URL = 'https://example.com/'
+          private_constant :PLACEHOLDER_URL
+
+          class << self
+            ##
+            # @param request [Rack::Request]
+            # @return [Hash{Symbol=>Object}]
+            def call(request)
+              ensure_enabled!
+              body = json_object(request)
+              report, selectors = assess(body)
+              Response.success(response: request.response, data: payload(report, selectors))
+            end
+
+            private
+
+            # @return [void]
+            def ensure_enabled!
+              raise ForbiddenError, 'Studio is disabled' unless Flags.studio_enabled?
+            end
+
+            # @param request [Rack::Request]
+            # @return [Hash]
+            def json_object(request)
+              raw = read_body(request)
+              return {} if raw.strip.empty?
+
+              parsed = JSON.parse(raw)
+              raise BadRequestError, 'Invalid JSON payload' unless parsed.is_a?(Hash)
+
+              parsed
+            rescue JSON::ParserError
+              raise BadRequestError, 'Invalid JSON payload'
+            end
+
+            # @param request [Rack::Request]
+            # @return [String]
+            def read_body(request)
+              limit = CreateFeed::MAX_BODY_BYTES
+              raise BadRequestError, 'Payload too large' if request.content_length.to_i > limit
+
+              request.body.read(limit + 1).to_s.tap do |raw|
+                request.body.rewind
+                raise BadRequestError, 'Payload too large' if raw.bytesize > limit
+              end
+            end
+
+            # @param body [Hash]
+            # @return [Array(Html2rss::Config::ValidationReport, Hash, nil)]
+            def assess(body)
+              return assess_yaml(body['yaml']) if body.key?('yaml') && !body['yaml'].nil?
+              raise BadRequestError, 'yaml or selectors is required' unless body.key?('selectors')
+
+              assess_fragment({ selectors: body['selectors'] })
+            end
+
+            # @param yaml [Object]
+            # @return [Array(Html2rss::Config::ValidationReport, Hash, nil)]
+            def assess_yaml(yaml)
+              assess_fragment(Html2rss::Config.from_yaml(yaml.to_s))
+            rescue ArgumentError, Psych::Exception => error
+              [Html2rss::Config::IssueMapper.parse_failure(error.message), nil]
+            end
+
+            # @param fragment [Hash]
+            # @return [Array(Html2rss::Config::ValidationReport, Hash, nil)]
+            def assess_fragment(fragment)
+              refined = RefinedSelectors.from_client(fragment)
+              [validation_report(refined.selectors), refined.selectors]
+            rescue BadRequestError => error
+              raise unless error.message.include?(' [')
+
+              selectors = fragment.is_a?(Hash) ? fragment[:selectors] || fragment['selectors'] : nil
+              [validation_report(selectors), selectors.is_a?(Hash) ? selectors : nil]
+            end
+
+            # @param selectors [Hash, nil]
+            # @return [Html2rss::Config::ValidationReport]
+            def validation_report(selectors)
+              Html2rss::Config.validate({ channel: { url: PLACEHOLDER_URL }, selectors: selectors || {} })
+            end
+
+            # @param report [Html2rss::Config::ValidationReport]
+            # @param selectors [Hash, nil]
+            # @return [Hash{Symbol=>Object}]
+            def payload(report, selectors)
+              yaml = selectors.is_a?(Hash) ? Html2rss::Config.to_yaml({ selectors: }) : nil
+              { report: report.to_h, selectors:, yaml: }
+            end
+          end
+        end
+      end
+    end
+  end
+end
diff --git a/app/web/config/flags.rb b/app/web/config/flags.rb
index 33a343fb..10b85497 100644
--- a/app/web/config/flags.rb
+++ b/app/web/config/flags.rb
@@ -24,6 +24,13 @@ module Flags # rubocop:disable Metrics/ModuleLength
           default: -> { development_or_test? },
           validator: nil
         ),
+        studio_enabled: Definition.new(
+          name: :studio_enabled,
+          env_key: 'STUDIO_ENABLED',
+          type: :boolean,
+          default: -> { development_or_test? },
+          validator: nil
+        ),
         config_catalog_enabled: Definition.new(
           name: :config_catalog_enabled,
           env_key: 'CONFIG_CATALOG_ENABLED',
@@ -68,7 +75,7 @@ module Flags # rubocop:disable Metrics/ModuleLength
         )
       }.freeze
       MANAGED_ENV_PREFIXES = %w[
-        AUTO_SOURCE_ CONFIG_CATALOG_ FEEDS_CACHE_ RATE_LIMIT_ RETRY_AFTER_
+        AUTO_SOURCE_ CONFIG_CATALOG_ FEEDS_CACHE_ RATE_LIMIT_ RETRY_AFTER_ STUDIO_
       ].freeze
       KNOWN_ENV_KEYS = Set.new(DEFINITIONS.values.map(&:env_key)).freeze
       DEV_OR_TEST_ENVS = Set['development', 'test'].freeze
@@ -109,6 +116,11 @@ def auto_source_enabled?
           fetch(:auto_source_enabled)
         end
 
+        # @return [Boolean]
+        def studio_enabled?
+          fetch(:studio_enabled)
+        end
+
         # Validates all known flags and managed env key prefixes.
         #
         # @return [void]
diff --git a/app/web/routes/api_v1/feed_routes.rb b/app/web/routes/api_v1/feed_routes.rb
index 2c54cce0..bdf48727 100644
--- a/app/web/routes/api_v1/feed_routes.rb
+++ b/app/web/routes/api_v1/feed_routes.rb
@@ -7,23 +7,44 @@ module ApiV1
         ##
         # Mounts feed-related API routes under `/api/v1/feeds`.
         module FeedRoutes
+          STUDIO_POSTS = {
+            'validate' => Api::V1::ValidateConfig,
+            'preview' => Api::V1::PreviewFeed,
+            'suggest_selectors' => Api::V1::SuggestSelectors
+          }.freeze
+
           class << self
             # @param router [Roda::RodaRequest]
             # @return [void]
             def call(router)
               router.on 'feeds' do
-                router.get String do |token|
-                  router.env[RequestTarget::ENV_KEY] = RequestTarget::FEED
-                  Feeds::Responder.call(request: router, target_kind: :token, identifier: token)
-                end
+                mount_studio_posts(router)
+                mount_token_get(router)
 
-                router.post do
-                  JSON.generate(Api::V1::CreateFeed.call(router))
-                end
+                router.post { JSON.generate(Api::V1::CreateFeed.call(router)) }
 
                 raise NotFoundError
               end
             end
+
+            private
+
+            # @param router [Roda::RodaRequest]
+            # @return [void]
+            def mount_studio_posts(router)
+              STUDIO_POSTS.each do |path, handler|
+                router.post(path) { JSON.generate(handler.call(router)) }
+              end
+            end
+
+            # @param router [Roda::RodaRequest]
+            # @return [void]
+            def mount_token_get(router)
+              router.get(String) do |token|
+                router.env[RequestTarget::ENV_KEY] = RequestTarget::FEED
+                Feeds::Responder.call(request: router, target_kind: :token, identifier: token)
+              end
+            end
           end
         end
       end
diff --git a/frontend/src/api/generated/index.ts b/frontend/src/api/generated/index.ts
index 56b4fe60..947952c1 100644
--- a/frontend/src/api/generated/index.ts
+++ b/frontend/src/api/generated/index.ts
@@ -1,4 +1,4 @@
 // This file is auto-generated by @hey-api/openapi-ts
 
-export { createFeed, getApiMetadata, getConfigCatalog, getHealthStatus, getLivenessProbe, getReadinessProbe, listStrategies, type Options, optionsConfigCatalog, renderFeedByToken } from './sdk.gen';
-export type { ClientOptions, CreateFeedData, CreateFeedError, CreateFeedErrors, CreateFeedResponse, CreateFeedResponses, GetApiMetadataData, GetApiMetadataResponse, GetApiMetadataResponses, GetConfigCatalogData, GetConfigCatalogError, GetConfigCatalogErrors, GetConfigCatalogResponse, GetConfigCatalogResponses, GetHealthStatusData, GetHealthStatusError, GetHealthStatusErrors, GetHealthStatusResponse, GetHealthStatusResponses, GetLivenessProbeData, GetLivenessProbeResponse, GetLivenessProbeResponses, GetReadinessProbeData, GetReadinessProbeResponse, GetReadinessProbeResponses, ListStrategiesData, ListStrategiesResponse, ListStrategiesResponses, OptionsConfigCatalogData, OptionsConfigCatalogResponse, OptionsConfigCatalogResponses, RenderFeedByTokenData, RenderFeedByTokenError, RenderFeedByTokenErrors, RenderFeedByTokenResponse, RenderFeedByTokenResponses } from './types.gen';
+export { createFeed, getApiMetadata, getConfigCatalog, getHealthStatus, getLivenessProbe, getReadinessProbe, listStrategies, type Options, optionsConfigCatalog, renderFeedByToken, validateFeedConfig } from './sdk.gen';
+export type { ClientOptions, CreateFeedData, CreateFeedError, CreateFeedErrors, CreateFeedResponse, CreateFeedResponses, GetApiMetadataData, GetApiMetadataResponse, GetApiMetadataResponses, GetConfigCatalogData, GetConfigCatalogError, GetConfigCatalogErrors, GetConfigCatalogResponse, GetConfigCatalogResponses, GetHealthStatusData, GetHealthStatusError, GetHealthStatusErrors, GetHealthStatusResponse, GetHealthStatusResponses, GetLivenessProbeData, GetLivenessProbeResponse, GetLivenessProbeResponses, GetReadinessProbeData, GetReadinessProbeResponse, GetReadinessProbeResponses, ListStrategiesData, ListStrategiesResponse, ListStrategiesResponses, OptionsConfigCatalogData, OptionsConfigCatalogResponse, OptionsConfigCatalogResponses, RenderFeedByTokenData, RenderFeedByTokenError, RenderFeedByTokenErrors, RenderFeedByTokenResponse, RenderFeedByTokenResponses, ValidateFeedConfigData, ValidateFeedConfigError, ValidateFeedConfigErrors, ValidateFeedConfigResponse, ValidateFeedConfigResponses } from './types.gen';
diff --git a/frontend/src/api/generated/sdk.gen.ts b/frontend/src/api/generated/sdk.gen.ts
index 858a3abc..27e18dba 100644
--- a/frontend/src/api/generated/sdk.gen.ts
+++ b/frontend/src/api/generated/sdk.gen.ts
@@ -2,7 +2,7 @@
 
 import { type Client, type ClientMeta, type Options as Options2, type RequestResult, type TDataShape, urlSearchParamsBodySerializer } from './client';
 import { client } from './client.gen';
-import type { CreateFeedData, CreateFeedErrors, CreateFeedResponses, GetApiMetadataData, GetApiMetadataResponses, GetConfigCatalogData, GetConfigCatalogErrors, GetConfigCatalogResponses, GetHealthStatusData, GetHealthStatusErrors, GetHealthStatusResponses, GetLivenessProbeData, GetLivenessProbeResponses, GetReadinessProbeData, GetReadinessProbeResponses, ListStrategiesData, ListStrategiesResponses, OptionsConfigCatalogData, OptionsConfigCatalogResponses, RenderFeedByTokenData, RenderFeedByTokenErrors, RenderFeedByTokenResponses } from './types.gen';
+import type { CreateFeedData, CreateFeedErrors, CreateFeedResponses, GetApiMetadataData, GetApiMetadataResponses, GetConfigCatalogData, GetConfigCatalogErrors, GetConfigCatalogResponses, GetHealthStatusData, GetHealthStatusErrors, GetHealthStatusResponses, GetLivenessProbeData, GetLivenessProbeResponses, GetReadinessProbeData, GetReadinessProbeResponses, ListStrategiesData, ListStrategiesResponses, OptionsConfigCatalogData, OptionsConfigCatalogResponses, RenderFeedByTokenData, RenderFeedByTokenErrors, RenderFeedByTokenResponses, ValidateFeedConfigData, ValidateFeedConfigErrors, ValidateFeedConfigResponses } from './types.gen';
 
 export type Options<TData extends TDataShape = TDataShape, ThrowOnError extends boolean = boolean, TResponse = unknown> = Options2<TData, ThrowOnError, TResponse> & {
   /**
@@ -69,6 +69,21 @@ export const createFeed = <ThrowOnError extends boolean = false>(options: Option
  */
 export const renderFeedByToken = <ThrowOnError extends boolean = false>(options: Options<RenderFeedByTokenData, ThrowOnError>): RequestResult<RenderFeedByTokenResponses, RenderFeedByTokenErrors, ThrowOnError> => (options.client ?? client).get<RenderFeedByTokenResponses, RenderFeedByTokenErrors, ThrowOnError>({ url: '/feeds/{token}', ...options });
 
+/**
+ * Validate a refined config
+ *
+ * Preview a refined feed
+ */
+export const validateFeedConfig = <ThrowOnError extends boolean = false>(options: Options<ValidateFeedConfigData, ThrowOnError>): RequestResult<ValidateFeedConfigResponses, ValidateFeedConfigErrors, ThrowOnError> => (options.client ?? client).post<ValidateFeedConfigResponses, ValidateFeedConfigErrors, ThrowOnError>({
+  security: [{ scheme: 'bearer', type: 'http' }],
+  url: '/feeds/{token}',
+  ...options,
+  headers: {
+    'Content-Type': 'application/json',
+    ...options.headers
+  }
+});
+
 /**
  * Authenticated health check
  *
diff --git a/frontend/src/api/generated/types.gen.ts b/frontend/src/api/generated/types.gen.ts
index f24843d1..28b4600b 100644
--- a/frontend/src/api/generated/types.gen.ts
+++ b/frontend/src/api/generated/types.gen.ts
@@ -298,6 +298,75 @@ export type RenderFeedByTokenResponses = {
 
 export type RenderFeedByTokenResponse = RenderFeedByTokenResponses[keyof RenderFeedByTokenResponses];
 
+export type ValidateFeedConfigData = {
+  body?: {
+    selectors?: {
+      items: {
+        enhance: boolean;
+        selector: string;
+      };
+    };
+    yaml?: string;
+  };
+  headers: {
+    Authorization: string;
+  };
+  path: {
+    token: string;
+  };
+  query?: never;
+  url: '/feeds/{token}';
+};
+
+export type ValidateFeedConfigErrors = {
+  /**
+   * rejects channel so the token url cannot be replaced
+   */
+  400: {
+    error: {
+      code: string;
+      kind: string;
+      message: string;
+      next_action: string;
+      retry_action: string;
+      retryable: boolean;
+    };
+    success: boolean;
+  };
+};
+
+export type ValidateFeedConfigError = ValidateFeedConfigErrors[keyof ValidateFeedConfigErrors];
+
+export type ValidateFeedConfigResponses = {
+  /**
+   * returns a parse issue for unparseable yaml
+   */
+  200: {
+    data: {
+      report: {
+        issues: Array<{
+          actual: unknown;
+          code: string;
+          expected: unknown;
+          message: string;
+          path: Array<string>;
+        }>;
+        success: boolean;
+      };
+      selectors: {
+        items: {
+          enhance: boolean;
+          selector: string;
+        };
+      } | null;
+      yaml: string | null;
+    };
+    success: boolean;
+  };
+};
+
+export type ValidateFeedConfigResponse = ValidateFeedConfigResponses[keyof ValidateFeedConfigResponses];
+
 export type GetHealthStatusData = {
   body?: never;
   headers: {
diff --git a/public/openapi.yaml b/public/openapi.yaml
index adafa5a9..0bee484d 100644
--- a/public/openapi.yaml
+++ b/public/openapi.yaml
@@ -619,6 +619,152 @@ paths:
       summary: Render feed by token
       tags:
       - Feeds
+    post:
+      description: Preview a refined feed
+      operationId: validateFeedConfig
+      parameters:
+      - in: header
+        name: Authorization
+        required: true
+        schema:
+          type: string
+      - in: path
+        name: token
+        required: true
+        schema:
+          type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              properties:
+                selectors:
+                  properties:
+                    items:
+                      properties:
+                        enhance:
+                          type: boolean
+                        selector:
+                          type: string
+                      required:
+                      - selector
+                      - enhance
+                      type: object
+                  required:
+                  - items
+                  type: object
+                yaml:
+                  type: string
+              type: object
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                properties:
+                  data:
+                    properties:
+                      report:
+                        properties:
+                          issues:
+                            items:
+                              properties:
+                                actual:
+                                  nullable: true
+                                code:
+                                  type: string
+                                expected:
+                                  nullable: true
+                                message:
+                                  type: string
+                                path:
+                                  items:
+                                    type: string
+                                  type: array
+                              required:
+                              - path
+                              - code
+                              - message
+                              - expected
+                              - actual
+                              type: object
+                            type: array
+                          success:
+                            type: boolean
+                        required:
+                        - success
+                        - issues
+                        type: object
+                      selectors:
+                        nullable: true
+                        properties:
+                          items:
+                            properties:
+                              enhance:
+                                type: boolean
+                              selector:
+                                type: string
+                            required:
+                            - selector
+                            - enhance
+                            type: object
+                        required:
+                        - items
+                        type: object
+                      yaml:
+                        nullable: true
+                        type: string
+                    required:
+                    - report
+                    - selectors
+                    - yaml
+                    type: object
+                  success:
+                    type: boolean
+                required:
+                - success
+                - data
+                type: object
+          description: returns a parse issue for unparseable yaml
+        '400':
+          content:
+            application/json:
+              schema:
+                properties:
+                  error:
+                    properties:
+                      code:
+                        type: string
+                      kind:
+                        type: string
+                      message:
+                        type: string
+                      next_action:
+                        type: string
+                      retry_action:
+                        type: string
+                      retryable:
+                        type: boolean
+                    required:
+                    - code
+                    - message
+                    - kind
+                    - retryable
+                    - next_action
+                    - retry_action
+                    type: object
+                  success:
+                    type: boolean
+                required:
+                - success
+                - error
+                type: object
+          description: rejects channel so the token url cannot be replaced
+      security:
+      - BearerAuth: []
+      summary: Validate a refined config
+      tags:
+      - Studio
   "/health":
     get:
       description: Authenticated health check
diff --git a/spec/html2rss/web/api/v1_spec.rb b/spec/html2rss/web/api/v1_spec.rb
index 95786d47..f30a4431 100644
--- a/spec/html2rss/web/api/v1_spec.rb
+++ b/spec/html2rss/web/api/v1_spec.rb
@@ -832,4 +832,109 @@ def relative_feed_link_header(token)
       expect(json.dig('error', 'message')).to eq('Payload too large')
     end
   end
+
+  describe 'POST /api/v1/feeds/validate', openapi: {
+    summary: 'Validate a refined config',
+    operation_id: 'validateFeedConfig',
+    tags: ['Studio']
+  } do
+    def post_validate(payload)
+      header 'Content-Type', 'application/json'
+      post '/api/v1/feeds/validate', payload.to_json
+    end
+
+    it 'returns a structured report for an allowlisted selectors object', :aggregate_failures do
+      post_validate(selectors: { items: { selector: 'article', enhance: true } })
+
+      json = expect_success_response(last_response)
+      expect(json.dig('data', 'report', 'success')).to be(true)
+      expect(json.dig('data', 'selectors', 'items', 'selector')).to eq('article')
+    end
+
+    it 'returns a parse issue for unparseable yaml' do
+      post_validate(yaml: "selectors: [\n")
+
+      json = expect_success_response(last_response)
+      expect(json.dig('data', 'report', 'issues', 0, 'code')).to eq('parse')
+    end
+
+    it 'rejects channel so the token url cannot be replaced' do
+      post_validate(yaml: "channel:\n  url: https://evil.example\nselectors:\n  items:\n    selector: article\n")
+
+      expect(last_response.status).to eq(400)
+      expect(JSON.parse(last_response.body).dig('error', 'message')).to eq('channel is not allowed')
+    end
+  end
+
+  describe 'POST /api/v1/feeds/preview', openapi: {
+    summary: 'Preview a refined feed',
+    operation_id: 'previewFeed',
+    tags: ['Studio'],
+    security: [{ 'BearerAuth' => [] }]
+  } do
+    let(:preview_result) do
+      Html2rss::Test::Result.new(
+        success: true, item_count: 2, sample_items: [{ 'title' => 'A' }], channel_title: 'Example',
+        channel_url: feed_url, strategy_used: :auto, duration_seconds: 0.1, validation_issues: [],
+        error_message: nil, failure_kind: nil, rss: '<rss>do-not-leak</rss>'
+      )
+    end
+
+    before do
+      allow(Html2rss).to receive(:test).and_return(preview_result)
+    end
+
+    it 'selects test fields and never returns the rss body', :aggregate_failures do
+      header 'Authorization', "Bearer #{admin_token}"
+      header 'Content-Type', 'application/json'
+      post '/api/v1/feeds/preview', { url: feed_url, selectors: { items: { selector: 'article' } } }.to_json
+
+      json = expect_success_response(last_response)
+      expect(json.fetch('data').keys).to contain_exactly(
+        'item_count', 'sample_items', 'quality_report', 'failure_kind', 'validation_issues'
+      )
+      expect(json.dig('data', 'item_count')).to eq(2)
+    end
+
+    it 'previews through the token generator config' do
+      header 'Authorization', "Bearer #{admin_token}"
+      header 'Content-Type', 'application/json'
+      selectors = Html2rss::Web::RefinedSelectors.from_client(selectors: { items: { selector: 'article' } })
+      post '/api/v1/feeds/preview', { url: feed_url, selectors: { items: { selector: 'article' } } }.to_json
+
+      strategy = Html2rss::Config.default_strategy_name.to_s
+      strategy = 'auto' if strategy.strip.empty?
+      expect(Html2rss).to have_received(:test).with(
+        Html2rss::Web::Feeds::GeneratorInput.for_token(url: feed_url, strategy:, selectors:),
+        min_items: 1
+      )
+    end
+  end
+
+  describe 'POST /api/v1/feeds/suggest_selectors', openapi: {
+    summary: 'Suggest selectors for a page',
+    operation_id: 'suggestSelectors',
+    tags: ['Studio'],
+    security: [{ 'BearerAuth' => [] }]
+  } do
+    let(:captured) do
+      instance_double(
+        Html2rss::Capture::CaptureResult,
+        config: { selectors: { items: { selector: 'article', enhance: false } } },
+        segment_strategy: :list,
+        admission_drops: { 'chrome' => 2 }
+      )
+    end
+
+    it 'returns the capture suggestion and its evidence', :aggregate_failures do
+      allow(Html2rss).to receive(:capture).and_return(captured)
+      header 'Authorization', "Bearer #{admin_token}"
+      header 'Content-Type', 'application/json'
+      post '/api/v1/feeds/suggest_selectors', { url: feed_url, items_selector: 'h2' }.to_json
+
+      json = expect_success_response(last_response)
+      expect(json.dig('data', 'segment_strategy')).to eq('list')
+      expect(json.dig('data', 'enhance')).to be(false)
+    end
+  end
 end

From 9aff9c0dbd05e9ba86e1cf4693965f1401812dba Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sat, 19 Sep 2026 22:23:33 +0200
Subject: [PATCH 008/108] feat(api): accept refined selectors on create and
 publish the studio contract

Create signs an optional allowlisted fragment into the token, and the OpenAPI hook now derives issue codes and accepted keys from the runtime sets so the published client cannot drift from the rule.
---
 app/web/api/v1/create_feed.rb           |  20 +-
 frontend/src/api/generated/index.ts     |   4 +-
 frontend/src/api/generated/sdk.gen.ts   |  52 +++-
 frontend/src/api/generated/types.gen.ts | 170 +++++++++---
 public/openapi.yaml                     | 355 +++++++++++++++++-------
 spec/html2rss/web/api/v1_spec.rb        |   8 +
 spec/support/openapi.rb                 |  67 ++++-
 7 files changed, 511 insertions(+), 165 deletions(-)

diff --git a/app/web/api/v1/create_feed.rb b/app/web/api/v1/create_feed.rb
index b3638f57..d01fc89b 100644
--- a/app/web/api/v1/create_feed.rb
+++ b/app/web/api/v1/create_feed.rb
@@ -18,6 +18,16 @@ module CreateFeed # rubocop:disable Metrics/ModuleLength
             (?:[/?#].*)?\z
           }ix
 
+          # Allowlists an optional selectors object before it is signed. Absent keeps legacy tokens valid.
+          #
+          # @param request [Rack::Request]
+          # @return [Html2rss::Web::RefinedSelectors, nil]
+          def self.selectors_for(request)
+            raw = request_params(request)['selectors']
+            raw.nil? ? nil : RefinedSelectors.from_client({ selectors: raw })
+          end
+          private_class_method :selectors_for
+
           class << self
             # Creates a feed and returns a normalized API success payload.
             #
@@ -26,8 +36,7 @@ class << self
             def call(request)
               account = require_account(request)
               params = build_create_params(request, account)
-              feed_data = create_feed(params, account)
-
+              feed_data = create_feed(params, account, request)
               emit_create(status: :success, details: { url: params.url })
               Response.success(response: request.response, status: 201,
                                data: { feed: feed_attributes(feed_data) }, meta: { created: true })
@@ -117,15 +126,14 @@ def normalized_input_url(raw_url)
               HOSTNAME_INPUT_REGEXP.match?(url) ? "https://#{url}" : url
             end
 
-            # Extracts via {Feeds::Service} before minting so create and serve share one expansion path.
-            #
             # @param params [Html2rss::Web::Api::V1::FeedMetadata::CreateParams]
             # @param account [Hash]
+            # @param request [Rack::Request]
             # @return [Html2rss::Web::Api::V1::FeedMetadata::Metadata]
-            def create_feed(params, account)
+            def create_feed(params, account, request)
               raise Html2rss::Web::AutoSourceDisabledError unless Flags.auto_source_enabled?
 
-              feed_token = Auth.generate_feed_token(account[:username], params.url)
+              feed_token = Auth.generate_feed_token(account[:username], params.url, selectors: selectors_for(request))
               raise Html2rss::Web::InternalServerError, 'Failed to create feed' unless feed_token
 
               result = Feeds::Service.call(resolved_source_for(feed_token))
diff --git a/frontend/src/api/generated/index.ts b/frontend/src/api/generated/index.ts
index 947952c1..4d175972 100644
--- a/frontend/src/api/generated/index.ts
+++ b/frontend/src/api/generated/index.ts
@@ -1,4 +1,4 @@
 // This file is auto-generated by @hey-api/openapi-ts
 
-export { createFeed, getApiMetadata, getConfigCatalog, getHealthStatus, getLivenessProbe, getReadinessProbe, listStrategies, type Options, optionsConfigCatalog, renderFeedByToken, validateFeedConfig } from './sdk.gen';
-export type { ClientOptions, CreateFeedData, CreateFeedError, CreateFeedErrors, CreateFeedResponse, CreateFeedResponses, GetApiMetadataData, GetApiMetadataResponse, GetApiMetadataResponses, GetConfigCatalogData, GetConfigCatalogError, GetConfigCatalogErrors, GetConfigCatalogResponse, GetConfigCatalogResponses, GetHealthStatusData, GetHealthStatusError, GetHealthStatusErrors, GetHealthStatusResponse, GetHealthStatusResponses, GetLivenessProbeData, GetLivenessProbeResponse, GetLivenessProbeResponses, GetReadinessProbeData, GetReadinessProbeResponse, GetReadinessProbeResponses, ListStrategiesData, ListStrategiesResponse, ListStrategiesResponses, OptionsConfigCatalogData, OptionsConfigCatalogResponse, OptionsConfigCatalogResponses, RenderFeedByTokenData, RenderFeedByTokenError, RenderFeedByTokenErrors, RenderFeedByTokenResponse, RenderFeedByTokenResponses, ValidateFeedConfigData, ValidateFeedConfigError, ValidateFeedConfigErrors, ValidateFeedConfigResponse, ValidateFeedConfigResponses } from './types.gen';
+export { createFeed, getApiMetadata, getConfigCatalog, getHealthStatus, getLivenessProbe, getReadinessProbe, listStrategies, type Options, optionsConfigCatalog, previewFeed, renderFeedByToken, suggestSelectors, validateFeedConfig } from './sdk.gen';
+export type { ClientOptions, CreateFeedData, CreateFeedError, CreateFeedErrors, CreateFeedResponse, CreateFeedResponses, GetApiMetadataData, GetApiMetadataResponse, GetApiMetadataResponses, GetConfigCatalogData, GetConfigCatalogError, GetConfigCatalogErrors, GetConfigCatalogResponse, GetConfigCatalogResponses, GetHealthStatusData, GetHealthStatusError, GetHealthStatusErrors, GetHealthStatusResponse, GetHealthStatusResponses, GetLivenessProbeData, GetLivenessProbeResponse, GetLivenessProbeResponses, GetReadinessProbeData, GetReadinessProbeResponse, GetReadinessProbeResponses, ListStrategiesData, ListStrategiesResponse, ListStrategiesResponses, OptionsConfigCatalogData, OptionsConfigCatalogResponse, OptionsConfigCatalogResponses, PreviewFeedData, PreviewFeedResponse, PreviewFeedResponses, RefinedSelectorKey, RenderFeedByTokenData, RenderFeedByTokenError, RenderFeedByTokenErrors, RenderFeedByTokenResponse, RenderFeedByTokenResponses, SuggestSelectorsData, SuggestSelectorsResponse, SuggestSelectorsResponses, ValidateFeedConfigData, ValidateFeedConfigError, ValidateFeedConfigErrors, ValidateFeedConfigResponse, ValidateFeedConfigResponses } from './types.gen';
diff --git a/frontend/src/api/generated/sdk.gen.ts b/frontend/src/api/generated/sdk.gen.ts
index 27e18dba..601fefc9 100644
--- a/frontend/src/api/generated/sdk.gen.ts
+++ b/frontend/src/api/generated/sdk.gen.ts
@@ -2,7 +2,7 @@
 
 import { type Client, type ClientMeta, type Options as Options2, type RequestResult, type TDataShape, urlSearchParamsBodySerializer } from './client';
 import { client } from './client.gen';
-import type { CreateFeedData, CreateFeedErrors, CreateFeedResponses, GetApiMetadataData, GetApiMetadataResponses, GetConfigCatalogData, GetConfigCatalogErrors, GetConfigCatalogResponses, GetHealthStatusData, GetHealthStatusErrors, GetHealthStatusResponses, GetLivenessProbeData, GetLivenessProbeResponses, GetReadinessProbeData, GetReadinessProbeResponses, ListStrategiesData, ListStrategiesResponses, OptionsConfigCatalogData, OptionsConfigCatalogResponses, RenderFeedByTokenData, RenderFeedByTokenErrors, RenderFeedByTokenResponses, ValidateFeedConfigData, ValidateFeedConfigErrors, ValidateFeedConfigResponses } from './types.gen';
+import type { CreateFeedData, CreateFeedErrors, CreateFeedResponses, GetApiMetadataData, GetApiMetadataResponses, GetConfigCatalogData, GetConfigCatalogErrors, GetConfigCatalogResponses, GetHealthStatusData, GetHealthStatusErrors, GetHealthStatusResponses, GetLivenessProbeData, GetLivenessProbeResponses, GetReadinessProbeData, GetReadinessProbeResponses, ListStrategiesData, ListStrategiesResponses, OptionsConfigCatalogData, OptionsConfigCatalogResponses, PreviewFeedData, PreviewFeedResponses, RenderFeedByTokenData, RenderFeedByTokenErrors, RenderFeedByTokenResponses, SuggestSelectorsData, SuggestSelectorsResponses, ValidateFeedConfigData, ValidateFeedConfigErrors, ValidateFeedConfigResponses } from './types.gen';
 
 export type Options<TData extends TDataShape = TDataShape, ThrowOnError extends boolean = boolean, TResponse = unknown> = Options2<TData, ThrowOnError, TResponse> & {
   /**
@@ -53,7 +53,6 @@ export const optionsConfigCatalog = <ThrowOnError extends boolean = false>(optio
  * Create a feed
  */
 export const createFeed = <ThrowOnError extends boolean = false>(options: Options<CreateFeedData, ThrowOnError>): RequestResult<CreateFeedResponses, CreateFeedErrors, ThrowOnError> => (options.client ?? client).post<CreateFeedResponses, CreateFeedErrors, ThrowOnError>({
-  security: [{ scheme: 'bearer', type: 'http' }],
   url: '/feeds',
   ...options,
   headers: {
@@ -63,20 +62,26 @@ export const createFeed = <ThrowOnError extends boolean = false>(options: Option
 });
 
 /**
- * Render feed by token
+ * Preview a refined feed
  *
- * Render feed by token
+ * Preview a refined feed
  */
-export const renderFeedByToken = <ThrowOnError extends boolean = false>(options: Options<RenderFeedByTokenData, ThrowOnError>): RequestResult<RenderFeedByTokenResponses, RenderFeedByTokenErrors, ThrowOnError> => (options.client ?? client).get<RenderFeedByTokenResponses, RenderFeedByTokenErrors, ThrowOnError>({ url: '/feeds/{token}', ...options });
+export const previewFeed = <ThrowOnError extends boolean = false>(options: Options<PreviewFeedData, ThrowOnError>): RequestResult<PreviewFeedResponses, unknown, ThrowOnError> => (options.client ?? client).post<PreviewFeedResponses, unknown, ThrowOnError>({
+  url: '/feeds/preview',
+  ...options,
+  headers: {
+    'Content-Type': 'application/json',
+    ...options.headers
+  }
+});
 
 /**
- * Validate a refined config
+ * Suggest selectors for a page
  *
- * Preview a refined feed
+ * Suggest selectors for a page
  */
-export const validateFeedConfig = <ThrowOnError extends boolean = false>(options: Options<ValidateFeedConfigData, ThrowOnError>): RequestResult<ValidateFeedConfigResponses, ValidateFeedConfigErrors, ThrowOnError> => (options.client ?? client).post<ValidateFeedConfigResponses, ValidateFeedConfigErrors, ThrowOnError>({
-  security: [{ scheme: 'bearer', type: 'http' }],
-  url: '/feeds/{token}',
+export const suggestSelectors = <ThrowOnError extends boolean = false>(options: Options<SuggestSelectorsData, ThrowOnError>): RequestResult<SuggestSelectorsResponses, unknown, ThrowOnError> => (options.client ?? client).post<SuggestSelectorsResponses, unknown, ThrowOnError>({
+  url: '/feeds/suggest_selectors',
   ...options,
   headers: {
     'Content-Type': 'application/json',
@@ -84,16 +89,33 @@ export const validateFeedConfig = <ThrowOnError extends boolean = false>(options
   }
 });
 
+/**
+ * Validate a refined config
+ *
+ * Validate a refined config
+ */
+export const validateFeedConfig = <ThrowOnError extends boolean = false>(options?: Options<ValidateFeedConfigData, ThrowOnError>): RequestResult<ValidateFeedConfigResponses, ValidateFeedConfigErrors, ThrowOnError> => (options?.client ?? client).post<ValidateFeedConfigResponses, ValidateFeedConfigErrors, ThrowOnError>({
+  url: '/feeds/validate',
+  ...options,
+  headers: {
+    'Content-Type': 'application/json',
+    ...options?.headers
+  }
+});
+
+/**
+ * Render feed by token
+ *
+ * Render feed by token
+ */
+export const renderFeedByToken = <ThrowOnError extends boolean = false>(options: Options<RenderFeedByTokenData, ThrowOnError>): RequestResult<RenderFeedByTokenResponses, RenderFeedByTokenErrors, ThrowOnError> => (options.client ?? client).get<RenderFeedByTokenResponses, RenderFeedByTokenErrors, ThrowOnError>({ url: '/feeds/{token}', ...options });
+
 /**
  * Authenticated health check
  *
  * Authenticated health check
  */
-export const getHealthStatus = <ThrowOnError extends boolean = false>(options: Options<GetHealthStatusData, ThrowOnError>): RequestResult<GetHealthStatusResponses, GetHealthStatusErrors, ThrowOnError> => (options.client ?? client).get<GetHealthStatusResponses, GetHealthStatusErrors, ThrowOnError>({
-  security: [{ scheme: 'bearer', type: 'http' }],
-  url: '/health',
-  ...options
-});
+export const getHealthStatus = <ThrowOnError extends boolean = false>(options: Options<GetHealthStatusData, ThrowOnError>): RequestResult<GetHealthStatusResponses, GetHealthStatusErrors, ThrowOnError> => (options.client ?? client).get<GetHealthStatusResponses, GetHealthStatusErrors, ThrowOnError>({ url: '/health', ...options });
 
 /**
  * Liveness probe
diff --git a/frontend/src/api/generated/types.gen.ts b/frontend/src/api/generated/types.gen.ts
index 28b4600b..f03da78d 100644
--- a/frontend/src/api/generated/types.gen.ts
+++ b/frontend/src/api/generated/types.gen.ts
@@ -4,6 +4,11 @@ export type ClientOptions = {
   baseUrl: 'https://api.html2rss.dev/api/v1' | 'http://127.0.0.1:4000/api/v1' | (string & {});
 };
 
+/**
+ * Root keys a client-authored config fragment may contain.
+ */
+export type RefinedSelectorKey = 'selectors';
+
 export type GetApiMetadataData = {
   body?: never;
   path?: never;
@@ -150,6 +155,12 @@ export type OptionsConfigCatalogResponse = OptionsConfigCatalogResponses[keyof O
 export type CreateFeedData = {
   body?: {
     name?: string;
+    selectors?: {
+      items: {
+        enhance: boolean;
+        selector: string;
+      };
+    };
     url: string;
   };
   headers: {
@@ -247,56 +258,79 @@ export type CreateFeedResponses = {
 
 export type CreateFeedResponse = CreateFeedResponses[keyof CreateFeedResponses];
 
-export type RenderFeedByTokenData = {
-  body?: never;
-  path: {
-    token: string;
+export type PreviewFeedData = {
+  body?: {
+    selectors: {
+      items: {
+        selector: string;
+      };
+    };
+    url: string;
+  };
+  headers: {
+    Authorization: string;
   };
+  path?: never;
   query?: never;
-  url: '/feeds/{token}';
+  url: '/feeds/preview';
 };
 
-export type RenderFeedByTokenErrors = {
-  /**
-   * returns unauthorized for invalid tokens
-   */
-  401: string;
+export type PreviewFeedResponses = {
   /**
-   * returns forbidden when auto source is disabled
-   */
-  403: string;
-  /**
-   * returns 422 for empty extraction feeds in xml representation
-   */
-  422: string;
-  /**
-   * returns 429 when rate limit is exceeded
+   * previews through the token generator config
    */
-  429: string;
-  /**
-   * returns non-cacheable feed errors when service generation fails
-   */
-  500: string;
-  /**
-   * returns 503 when the scraper queue times out
-   */
-  503: string;
-  /**
-   * returns 504 when the gateway times out
-   */
-  504: string;
+  200: {
+    data: {
+      failure_kind: unknown;
+      item_count: number;
+      quality_report: unknown;
+      sample_items: Array<{
+        title: string;
+      }>;
+      validation_issues: Array<unknown>;
+    };
+    success: boolean;
+  };
 };
 
-export type RenderFeedByTokenError = RenderFeedByTokenErrors[keyof RenderFeedByTokenErrors];
+export type PreviewFeedResponse = PreviewFeedResponses[keyof PreviewFeedResponses];
 
-export type RenderFeedByTokenResponses = {
+export type SuggestSelectorsData = {
+  body?: {
+    items_selector: string;
+    url: string;
+  };
+  headers: {
+    Authorization: string;
+  };
+  path?: never;
+  query?: never;
+  url: '/feeds/suggest_selectors';
+};
+
+export type SuggestSelectorsResponses = {
   /**
-   * renders feed for a valid token
+   * returns the capture suggestion and its evidence
    */
-  200: string;
+  200: {
+    data: {
+      admission_drops: {
+        chrome: number;
+      };
+      enhance: boolean;
+      segment_strategy: string;
+      selectors: {
+        items: {
+          enhance: boolean;
+          selector: string;
+        };
+      };
+    };
+    success: boolean;
+  };
 };
 
-export type RenderFeedByTokenResponse = RenderFeedByTokenResponses[keyof RenderFeedByTokenResponses];
+export type SuggestSelectorsResponse = SuggestSelectorsResponses[keyof SuggestSelectorsResponses];
 
 export type ValidateFeedConfigData = {
   body?: {
@@ -308,14 +342,9 @@ export type ValidateFeedConfigData = {
     };
     yaml?: string;
   };
-  headers: {
-    Authorization: string;
-  };
-  path: {
-    token: string;
-  };
+  path?: never;
   query?: never;
-  url: '/feeds/{token}';
+  url: '/feeds/validate';
 };
 
 export type ValidateFeedConfigErrors = {
@@ -346,7 +375,7 @@ export type ValidateFeedConfigResponses = {
       report: {
         issues: Array<{
           actual: unknown;
-          code: string;
+          code: 'constraint' | 'invalid_value' | 'missing_key' | 'parse' | 'type_mismatch' | 'unknown_value';
           expected: unknown;
           message: string;
           path: Array<string>;
@@ -367,6 +396,57 @@ export type ValidateFeedConfigResponses = {
 
 export type ValidateFeedConfigResponse = ValidateFeedConfigResponses[keyof ValidateFeedConfigResponses];
 
+export type RenderFeedByTokenData = {
+  body?: never;
+  path: {
+    token: string;
+  };
+  query?: never;
+  url: '/feeds/{token}';
+};
+
+export type RenderFeedByTokenErrors = {
+  /**
+   * returns unauthorized for invalid tokens
+   */
+  401: string;
+  /**
+   * returns forbidden when auto source is disabled
+   */
+  403: string;
+  /**
+   * returns 422 for empty extraction feeds in xml representation
+   */
+  422: string;
+  /**
+   * returns 429 when rate limit is exceeded
+   */
+  429: string;
+  /**
+   * returns non-cacheable feed errors when service generation fails
+   */
+  500: string;
+  /**
+   * returns 503 when the scraper queue times out
+   */
+  503: string;
+  /**
+   * returns 504 when the gateway times out
+   */
+  504: string;
+};
+
+export type RenderFeedByTokenError = RenderFeedByTokenErrors[keyof RenderFeedByTokenErrors];
+
+export type RenderFeedByTokenResponses = {
+  /**
+   * renders feed for a valid token
+   */
+  200: string;
+};
+
+export type RenderFeedByTokenResponse = RenderFeedByTokenResponses[keyof RenderFeedByTokenResponses];
+
 export type GetHealthStatusData = {
   body?: never;
   headers: {
diff --git a/public/openapi.yaml b/public/openapi.yaml
index 0bee484d..095dee2f 100644
--- a/public/openapi.yaml
+++ b/public/openapi.yaml
@@ -323,6 +323,21 @@ paths:
               properties:
                 name:
                   type: string
+                selectors:
+                  properties:
+                    items:
+                      properties:
+                        enhance:
+                          type: boolean
+                        selector:
+                          type: string
+                      required:
+                      - selector
+                      - enhance
+                      type: object
+                  required:
+                  - items
+                  type: object
                 url:
                   type: string
               required:
@@ -529,110 +544,163 @@ paths:
       summary: Create a feed
       tags:
       - Feeds
-  "/feeds/{token}":
-    get:
-      description: Render feed by token
-      operationId: renderFeedByToken
+  "/feeds/preview":
+    post:
+      description: Preview a refined feed
+      operationId: previewFeed
       parameters:
-      - in: path
-        name: token
+      - in: header
+        name: Authorization
         required: true
         schema:
           type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              properties:
+                selectors:
+                  properties:
+                    items:
+                      properties:
+                        selector:
+                          type: string
+                      required:
+                      - selector
+                      type: object
+                  required:
+                  - items
+                  type: object
+                url:
+                  type: string
+              required:
+              - url
+              - selectors
+              type: object
       responses:
         '200':
           content:
-            application/feed+json:
-              schema:
-                type: string
-            application/xml:
-              schema:
-                type: string
-          description: renders feed for a valid token
-        '401':
-          content:
-            text/plain:
-              example: 'Failed to generate feed: Invalid token'
-              schema:
-                type: string
-          description: returns unauthorized for invalid tokens
-        '403':
-          content:
-            text/plain:
-              example: 'Failed to generate feed: Invalid token'
-              schema:
-                type: string
-          description: returns forbidden when auto source is disabled
-        '422':
-          content:
-            text/plain:
-              example: We could not extract feed items from this page yet. Try a more
-                specific listing URL or explicit selectors.
-              schema:
-                type: string
-          description: returns 422 for empty extraction feeds in xml representation
-        '429':
-          content:
-            text/plain:
-              example: 'Failed to generate feed: Invalid token'
-              schema:
-                type: string
-          description: returns 429 when rate limit is exceeded
-          headers:
-            Retry-After:
-              description: The number of seconds to wait before retrying the request.
-              schema:
-                type: integer
-        '500':
-          content:
-            text/plain:
-              example: 'Failed to generate feed: Invalid token'
-              schema:
-                type: string
-          description: returns non-cacheable feed errors when service generation fails
-        '503':
-          content:
-            text/plain:
-              example: 'Failed to generate feed: Invalid token'
-              schema:
-                type: string
-          description: returns 503 when the scraper queue times out
-          headers:
-            Retry-After:
-              description: The number of seconds to wait before retrying the request.
-              schema:
-                type: integer
-        '504':
-          content:
-            text/plain:
-              example: 'Failed to generate feed: Invalid token'
-              schema:
-                type: string
-          description: returns 504 when the gateway times out
-          headers:
-            Retry-After:
-              description: The number of seconds to wait before retrying the request.
+            application/json:
               schema:
-                type: integer
+                properties:
+                  data:
+                    properties:
+                      failure_kind:
+                        nullable: true
+                      item_count:
+                        type: integer
+                      quality_report:
+                        nullable: true
+                      sample_items:
+                        items:
+                          properties:
+                            title:
+                              type: string
+                          required:
+                          - title
+                          type: object
+                        type: array
+                      validation_issues:
+                        items: {}
+                        type: array
+                    required:
+                    - item_count
+                    - sample_items
+                    - quality_report
+                    - failure_kind
+                    - validation_issues
+                    type: object
+                  success:
+                    type: boolean
+                required:
+                - success
+                - data
+                type: object
+          description: previews through the token generator config
       security:
-      - {}
-      summary: Render feed by token
+      - BearerAuth: []
+      summary: Preview a refined feed
       tags:
-      - Feeds
+      - Studio
+  "/feeds/suggest_selectors":
     post:
-      description: Preview a refined feed
-      operationId: validateFeedConfig
+      description: Suggest selectors for a page
+      operationId: suggestSelectors
       parameters:
       - in: header
         name: Authorization
         required: true
         schema:
           type: string
-      - in: path
-        name: token
-        required: true
-        schema:
-          type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              properties:
+                items_selector:
+                  type: string
+                url:
+                  type: string
+              required:
+              - url
+              - items_selector
+              type: object
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                properties:
+                  data:
+                    properties:
+                      admission_drops:
+                        properties:
+                          chrome:
+                            type: integer
+                        required:
+                        - chrome
+                        type: object
+                      enhance:
+                        type: boolean
+                      segment_strategy:
+                        type: string
+                      selectors:
+                        properties:
+                          items:
+                            properties:
+                              enhance:
+                                type: boolean
+                              selector:
+                                type: string
+                            required:
+                            - selector
+                            - enhance
+                            type: object
+                        required:
+                        - items
+                        type: object
+                    required:
+                    - selectors
+                    - segment_strategy
+                    - admission_drops
+                    - enhance
+                    type: object
+                  success:
+                    type: boolean
+                required:
+                - success
+                - data
+                type: object
+          description: returns the capture suggestion and its evidence
+      security:
+      - BearerAuth: []
+      summary: Suggest selectors for a page
+      tags:
+      - Studio
+  "/feeds/validate":
+    post:
+      description: Validate a refined config
+      operationId: validateFeedConfig
       requestBody:
         content:
           application/json:
@@ -673,6 +741,13 @@ paths:
                                   nullable: true
                                 code:
                                   type: string
+                                  enum:
+                                  - constraint
+                                  - invalid_value
+                                  - missing_key
+                                  - parse
+                                  - type_mismatch
+                                  - unknown_value
                                 expected:
                                   nullable: true
                                 message:
@@ -760,11 +835,99 @@ paths:
                 - error
                 type: object
           description: rejects channel so the token url cannot be replaced
-      security:
-      - BearerAuth: []
       summary: Validate a refined config
       tags:
       - Studio
+  "/feeds/{token}":
+    get:
+      description: Render feed by token
+      operationId: renderFeedByToken
+      parameters:
+      - in: path
+        name: token
+        required: true
+        schema:
+          type: string
+      responses:
+        '200':
+          content:
+            application/feed+json:
+              schema:
+                type: string
+            application/xml:
+              schema:
+                type: string
+          description: renders feed for a valid token
+        '401':
+          content:
+            text/plain:
+              example: 'Failed to generate feed: Invalid token'
+              schema:
+                type: string
+          description: returns unauthorized for invalid tokens
+        '403':
+          content:
+            text/plain:
+              example: 'Failed to generate feed: Invalid token'
+              schema:
+                type: string
+          description: returns forbidden when auto source is disabled
+        '422':
+          content:
+            text/plain:
+              example: We could not extract feed items from this page yet. Try a more
+                specific listing URL or explicit selectors.
+              schema:
+                type: string
+          description: returns 422 for empty extraction feeds in xml representation
+        '429':
+          content:
+            text/plain:
+              example: 'Failed to generate feed: Invalid token'
+              schema:
+                type: string
+          description: returns 429 when rate limit is exceeded
+          headers:
+            Retry-After:
+              description: The number of seconds to wait before retrying the request.
+              schema:
+                type: integer
+        '500':
+          content:
+            text/plain:
+              example: 'Failed to generate feed: Invalid token'
+              schema:
+                type: string
+          description: returns non-cacheable feed errors when service generation fails
+        '503':
+          content:
+            text/plain:
+              example: 'Failed to generate feed: Invalid token'
+              schema:
+                type: string
+          description: returns 503 when the scraper queue times out
+          headers:
+            Retry-After:
+              description: The number of seconds to wait before retrying the request.
+              schema:
+                type: integer
+        '504':
+          content:
+            text/plain:
+              example: 'Failed to generate feed: Invalid token'
+              schema:
+                type: string
+          description: returns 504 when the gateway times out
+          headers:
+            Retry-After:
+              description: The number of seconds to wait before retrying the request.
+              schema:
+                type: integer
+      security:
+      - {}
+      summary: Render feed by token
+      tags:
+      - Feeds
   "/health":
     get:
       description: Authenticated health check
@@ -1023,12 +1186,12 @@ paths:
       tags:
       - Strategies
 components:
-  securitySchemes:
-    BearerAuth:
-      description: Bearer token authentication for API access.
-      type: http
-      scheme: bearer
-      bearerFormat: JWT
+  schemas:
+    RefinedSelectorKey:
+      description: Root keys a client-authored config fragment may contain.
+      enum:
+      - selectors
+      type: string
 tags:
 - name: Root
   description: API metadata and service-level information.
@@ -1040,3 +1203,5 @@ tags:
   description: Feed extraction strategy discovery.
 - name: Feeds
   description: Feed creation and feed rendering operations.
+- name: Studio
+  description: Validate, preview, and suggest refined feed configs.
diff --git a/spec/html2rss/web/api/v1_spec.rb b/spec/html2rss/web/api/v1_spec.rb
index f30a4431..1d937f4d 100644
--- a/spec/html2rss/web/api/v1_spec.rb
+++ b/spec/html2rss/web/api/v1_spec.rb
@@ -728,6 +728,14 @@ def relative_feed_link_header(token)
       retry_action: 'none'
     }
 
+    it 'signs optional refined selectors into the feed token', :aggregate_failures do
+      post_feed_request(url: feed_url, selectors: { items: { selector: 'article', enhance: true } })
+
+      token = expect_success_response(last_response).dig('data', 'feed', 'feed_token')
+      decoded = Html2rss::Web::Auth.validate_and_decode_feed_token(token)
+      expect(decoded.selectors.to_config_fragment.dig(:selectors, :items, :selector)).to eq('article')
+    end
+
     it 'creates a feed when request is valid', :aggregate_failures do
       header 'Authorization', "Bearer #{admin_token}"
       header 'Content-Type', 'application/json'
diff --git a/spec/support/openapi.rb b/spec/support/openapi.rb
index 11c3188c..27bc805b 100644
--- a/spec/support/openapi.rb
+++ b/spec/support/openapi.rb
@@ -1,5 +1,63 @@
 # frozen_string_literal: true
 
+##
+# Stamps the published document from runtime allowlists so the contract cannot drift.
+module OpenapiRuntimeContract
+  module_function
+
+  # @param spec [Hash]
+  # @return [void]
+  def stamp(spec)
+    walk(spec) { |node| stamp_issue_code(node) }
+    publish_allowed_keys(spec)
+  end
+
+  # @param node [Object]
+  # @return [void]
+  def walk(node, &)
+    case node
+    in Hash
+      yield node
+      node.each_value { walk(it, &) }
+    in Array
+      node.each { walk(it, &) }
+    else
+      nil
+    end
+  end
+
+  # @param node [Hash]
+  # @return [void]
+  def stamp_issue_code(node)
+    properties = node['properties']
+    return unless properties.is_a?(Hash) && issue_schema?(properties)
+
+    code = properties['code']
+    return unless code.is_a?(Hash)
+
+    code['type'] = 'string'
+    # Data.define publishes this Set on Config, not on ValidationIssue.
+    code['enum'] = Html2rss::Config::CODES.map(&:to_s).sort
+  end
+
+  # @param properties [Hash]
+  # @return [Boolean]
+  def issue_schema?(properties)
+    %w[actual code expected message path].all? { properties.key?(it) }
+  end
+
+  # @param spec [Hash]
+  # @return [void]
+  def publish_allowed_keys(spec)
+    schemas = (spec['components'] ||= {})['schemas'] ||= {}
+    schemas['RefinedSelectorKey'] = {
+      'description' => 'Root keys a client-authored config fragment may contain.',
+      'enum' => Html2rss::Web::RefinedSelectors::ALLOWED_KEYS.map(&:to_s).sort,
+      'type' => 'string'
+    }
+  end
+end
+
 if ENV['OPENAPI']
   require 'rspec/openapi'
 
@@ -144,10 +202,12 @@
     path_map = spec['paths'] || spec[:paths]
     next unless path_map.is_a?(Hash)
 
+    studio_segment = Regexp.union(Html2rss::Web::Routes::ApiV1::FeedRoutes::STUDIO_POSTS.keys).source
+    token_path = %r{\A/api/v1/feeds/(?!(?:#{studio_segment})\z)[^/]+\z}
     normalized_paths = {}
     path_map.each do |raw_path, operation|
       original_path = raw_path.to_s
-      normalized = if original_path.match?(%r{\A/api/v1/feeds/[^/]+\z})
+      normalized = if original_path.match?(token_path)
                      '/feeds/{token}'
                    elsif original_path.start_with?('/api/v1')
                      original_path.delete_prefix('/api/v1')
@@ -228,7 +288,8 @@
       { 'name' => 'Catalog', 'description' => 'Public feed-directory catalog metadata.' },
       { 'name' => 'Health', 'description' => 'Health and readiness endpoints.' },
       { 'name' => 'Strategies', 'description' => 'Feed extraction strategy discovery.' },
-      { 'name' => 'Feeds', 'description' => 'Feed creation and feed rendering operations.' }
+      { 'name' => 'Feeds', 'description' => 'Feed creation and feed rendering operations.' },
+      { 'name' => 'Studio', 'description' => 'Validate, preview, and suggest refined feed configs.' }
     ]
 
     if spec.key?('tags')
@@ -236,5 +297,7 @@
     else
       spec[:tags] = tags
     end
+
+    OpenapiRuntimeContract.stamp(spec)
   end
 end

From d0117e9803bc83a55e256036507065de6c458e8c Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sat, 19 Sep 2026 22:42:55 +0200
Subject: [PATCH 009/108] fix(api): keep BearerAuth when publishing the studio
 schema

`publish_allowed_keys` wrote `spec['components']` while rspec-openapi seeds
`spec[:components]` with `securitySchemes` (symbol-keyed, see
rspec-openapi's DefaultSchema). The string-keyed write shadowed that hash on
dump, so `public/openapi.yaml` published four `BearerAuth: []` requirements
against a scheme that no longer existed, and the generated frontend client
dropped bearer security from createFeed, previewFeed, suggestSelectors and
getHealthStatus.

Reuse whichever key form the document already carries -- the same string/symbol
grammar the tags and paths stamps already use -- and merge into the existing
components hash instead of replacing it.

Arm `openapi-lint` in `ci-ready` so this class of defect fails the gate:
`openapi-verify` only diffs the regenerated file against itself and never sees
a dangling security reference. Redocly was green before the studio endpoints
landed, so the two publish defects those endpoints introduced are fixed here
too: ValidationIssue `expected`/`actual` are JSON-ish or nil and now publish as
open schemas (OAS 3.0 rejects `nullable` without a sibling `type`), and preview
gains a recorded empty-extraction example so `failure_kind` and
`quality_report` publish a type next to their `nullable`.

The remaining Redocly error (`security-defined` on POST /feeds/validate) is
real: that operation is still unauthenticated. It is fixed in the next commit.
---
 Makefile                                |  3 +-
 frontend/src/api/generated/sdk.gen.ts   |  9 +++++-
 frontend/src/api/generated/types.gen.ts | 15 ++++++++--
 public/openapi.yaml                     | 29 +++++++++++++++++--
 spec/html2rss/web/api/v1_spec.rb        | 21 ++++++++++++++
 spec/support/openapi.rb                 | 38 ++++++++++++++++++++++---
 6 files changed, 105 insertions(+), 10 deletions(-)

diff --git a/Makefile b/Makefile
index c4444eb7..789dac75 100644
--- a/Makefile
+++ b/Makefile
@@ -111,10 +111,11 @@ ready: ## Pre-commit gate (quick checks + RSpec)
 	bundle exec rspec
 	@echo "Pre-commit checks complete!"
 
-ci-ready: ## CI parity gate (ready + OpenAPI verify + frontend e2e smoke)
+ci-ready: ## CI parity gate (ready + OpenAPI verify/lint + frontend e2e smoke)
 	@echo "Running CI parity checks..."
 	$(MAKE) ready
 	$(MAKE) openapi-verify
+	$(MAKE) openapi-lint
 	$(MAKE) test-frontend-e2e
 	@echo "CI parity checks complete!"
 
diff --git a/frontend/src/api/generated/sdk.gen.ts b/frontend/src/api/generated/sdk.gen.ts
index 601fefc9..ca91cce0 100644
--- a/frontend/src/api/generated/sdk.gen.ts
+++ b/frontend/src/api/generated/sdk.gen.ts
@@ -53,6 +53,7 @@ export const optionsConfigCatalog = <ThrowOnError extends boolean = false>(optio
  * Create a feed
  */
 export const createFeed = <ThrowOnError extends boolean = false>(options: Options<CreateFeedData, ThrowOnError>): RequestResult<CreateFeedResponses, CreateFeedErrors, ThrowOnError> => (options.client ?? client).post<CreateFeedResponses, CreateFeedErrors, ThrowOnError>({
+  security: [{ scheme: 'bearer', type: 'http' }],
   url: '/feeds',
   ...options,
   headers: {
@@ -67,6 +68,7 @@ export const createFeed = <ThrowOnError extends boolean = false>(options: Option
  * Preview a refined feed
  */
 export const previewFeed = <ThrowOnError extends boolean = false>(options: Options<PreviewFeedData, ThrowOnError>): RequestResult<PreviewFeedResponses, unknown, ThrowOnError> => (options.client ?? client).post<PreviewFeedResponses, unknown, ThrowOnError>({
+  security: [{ scheme: 'bearer', type: 'http' }],
   url: '/feeds/preview',
   ...options,
   headers: {
@@ -81,6 +83,7 @@ export const previewFeed = <ThrowOnError extends boolean = false>(options: Optio
  * Suggest selectors for a page
  */
 export const suggestSelectors = <ThrowOnError extends boolean = false>(options: Options<SuggestSelectorsData, ThrowOnError>): RequestResult<SuggestSelectorsResponses, unknown, ThrowOnError> => (options.client ?? client).post<SuggestSelectorsResponses, unknown, ThrowOnError>({
+  security: [{ scheme: 'bearer', type: 'http' }],
   url: '/feeds/suggest_selectors',
   ...options,
   headers: {
@@ -115,7 +118,11 @@ export const renderFeedByToken = <ThrowOnError extends boolean = false>(options:
  *
  * Authenticated health check
  */
-export const getHealthStatus = <ThrowOnError extends boolean = false>(options: Options<GetHealthStatusData, ThrowOnError>): RequestResult<GetHealthStatusResponses, GetHealthStatusErrors, ThrowOnError> => (options.client ?? client).get<GetHealthStatusResponses, GetHealthStatusErrors, ThrowOnError>({ url: '/health', ...options });
+export const getHealthStatus = <ThrowOnError extends boolean = false>(options: Options<GetHealthStatusData, ThrowOnError>): RequestResult<GetHealthStatusResponses, GetHealthStatusErrors, ThrowOnError> => (options.client ?? client).get<GetHealthStatusResponses, GetHealthStatusErrors, ThrowOnError>({
+  security: [{ scheme: 'bearer', type: 'http' }],
+  url: '/health',
+  ...options
+});
 
 /**
  * Liveness probe
diff --git a/frontend/src/api/generated/types.gen.ts b/frontend/src/api/generated/types.gen.ts
index f03da78d..b3ba6927 100644
--- a/frontend/src/api/generated/types.gen.ts
+++ b/frontend/src/api/generated/types.gen.ts
@@ -281,9 +281,14 @@ export type PreviewFeedResponses = {
    */
   200: {
     data: {
-      failure_kind: unknown;
+      failure_kind: string | null;
       item_count: number;
-      quality_report: unknown;
+      quality_report: {
+        metrics: {
+          short_title_count: number;
+        };
+        warnings: Array<string>;
+      } | null;
       sample_items: Array<{
         title: string;
       }>;
@@ -374,8 +379,14 @@ export type ValidateFeedConfigResponses = {
     data: {
       report: {
         issues: Array<{
+          /**
+           * JSON-ish value, or null when the issue carries none.
+           */
           actual: unknown;
           code: 'constraint' | 'invalid_value' | 'missing_key' | 'parse' | 'type_mismatch' | 'unknown_value';
+          /**
+           * JSON-ish value, or null when the issue carries none.
+           */
           expected: unknown;
           message: string;
           path: Array<string>;
diff --git a/public/openapi.yaml b/public/openapi.yaml
index 095dee2f..37afe559 100644
--- a/public/openapi.yaml
+++ b/public/openapi.yaml
@@ -587,10 +587,27 @@ paths:
                     properties:
                       failure_kind:
                         nullable: true
+                        type: string
                       item_count:
                         type: integer
                       quality_report:
                         nullable: true
+                        properties:
+                          metrics:
+                            properties:
+                              short_title_count:
+                                type: integer
+                            required:
+                            - short_title_count
+                            type: object
+                          warnings:
+                            items:
+                              type: string
+                            type: array
+                        required:
+                        - warnings
+                        - metrics
+                        type: object
                       sample_items:
                         items:
                           properties:
@@ -738,7 +755,8 @@ paths:
                             items:
                               properties:
                                 actual:
-                                  nullable: true
+                                  description: JSON-ish value, or null when the issue
+                                    carries none.
                                 code:
                                   type: string
                                   enum:
@@ -749,7 +767,8 @@ paths:
                                   - type_mismatch
                                   - unknown_value
                                 expected:
-                                  nullable: true
+                                  description: JSON-ish value, or null when the issue
+                                    carries none.
                                 message:
                                   type: string
                                 path:
@@ -1186,6 +1205,12 @@ paths:
       tags:
       - Strategies
 components:
+  securitySchemes:
+    BearerAuth:
+      description: Bearer token authentication for API access.
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
   schemas:
     RefinedSelectorKey:
       description: Root keys a client-authored config fragment may contain.
diff --git a/spec/html2rss/web/api/v1_spec.rb b/spec/html2rss/web/api/v1_spec.rb
index 1d937f4d..ba4f48d8 100644
--- a/spec/html2rss/web/api/v1_spec.rb
+++ b/spec/html2rss/web/api/v1_spec.rb
@@ -887,6 +887,16 @@ def post_validate(payload)
         error_message: nil, failure_kind: nil, rss: '<rss>do-not-leak</rss>'
       )
     end
+    let(:failed_preview_result) do
+      Html2rss::Test::Result.new(
+        success: false, item_count: 0, sample_items: [], channel_title: nil,
+        channel_url: feed_url, strategy_used: :auto, duration_seconds: 0.1, validation_issues: [],
+        error_message: 'no items', failure_kind: Html2rss::Test::FailureKind.new(name: :min_items), rss: nil,
+        quality_report: Html2rss::Test::QualityReport.new(
+          warnings: [:short_titles], metrics: { 'short_title_count' => 2 }, native_feed: nil, defer_reason: nil
+        )
+      )
+    end
 
     before do
       allow(Html2rss).to receive(:test).and_return(preview_result)
@@ -904,6 +914,17 @@ def post_validate(payload)
       expect(json.dig('data', 'item_count')).to eq(2)
     end
 
+    it 'reports the failure kind and quality report when extraction comes up empty', :aggregate_failures do
+      allow(Html2rss).to receive(:test).and_return(failed_preview_result)
+      header 'Authorization', "Bearer #{admin_token}"
+      header 'Content-Type', 'application/json'
+      post '/api/v1/feeds/preview', { url: feed_url, selectors: { items: { selector: 'article' } } }.to_json
+
+      json = expect_success_response(last_response)
+      expect(json.dig('data', 'failure_kind')).to eq('min_items')
+      expect(json.dig('data', 'quality_report', 'warnings')).to eq(['short_titles'])
+    end
+
     it 'previews through the token generator config' do
       header 'Authorization', "Bearer #{admin_token}"
       header 'Content-Type', 'application/json'
diff --git a/spec/support/openapi.rb b/spec/support/openapi.rb
index 27bc805b..e0e21d04 100644
--- a/spec/support/openapi.rb
+++ b/spec/support/openapi.rb
@@ -8,7 +8,7 @@ module OpenapiRuntimeContract
   # @param spec [Hash]
   # @return [void]
   def stamp(spec)
-    walk(spec) { |node| stamp_issue_code(node) }
+    walk(spec) { |node| stamp_issue_schema(node) }
     publish_allowed_keys(spec)
   end
 
@@ -28,11 +28,18 @@ def walk(node, &)
 
   # @param node [Hash]
   # @return [void]
-  def stamp_issue_code(node)
+  def stamp_issue_schema(node)
     properties = node['properties']
     return unless properties.is_a?(Hash) && issue_schema?(properties)
 
-    code = properties['code']
+    stamp_issue_code(properties['code'])
+    stamp_open_value(properties['expected'])
+    stamp_open_value(properties['actual'])
+  end
+
+  # @param code [Object]
+  # @return [void]
+  def stamp_issue_code(code)
     return unless code.is_a?(Hash)
 
     code['type'] = 'string'
@@ -40,6 +47,18 @@ def stamp_issue_code(node)
     code['enum'] = Html2rss::Config::CODES.map(&:to_s).sort
   end
 
+  # ValidationIssue carries expected/actual as JSON-ish or nil, which OAS 3.0
+  # cannot type; a bare `nullable` without a sibling `type` is invalid there.
+  #
+  # @param value [Object]
+  # @return [void]
+  def stamp_open_value(value)
+    return unless value.is_a?(Hash)
+
+    value.delete('nullable')
+    value['description'] = 'JSON-ish value, or null when the issue carries none.'
+  end
+
   # @param properties [Hash]
   # @return [Boolean]
   def issue_schema?(properties)
@@ -49,13 +68,24 @@ def issue_schema?(properties)
   # @param spec [Hash]
   # @return [void]
   def publish_allowed_keys(spec)
-    schemas = (spec['components'] ||= {})['schemas'] ||= {}
+    schemas = section(section(spec, :components), :schemas)
     schemas['RefinedSelectorKey'] = {
       'description' => 'Root keys a client-authored config fragment may contain.',
       'enum' => Html2rss::Web::RefinedSelectors::ALLOWED_KEYS.map(&:to_s).sort,
       'type' => 'string'
     }
   end
+
+  # rspec-openapi seeds `components` symbol-keyed (`securitySchemes`), so a
+  # string-keyed write would shadow it and drop BearerAuth on dump.
+  #
+  # @param node [Hash]
+  # @param name [Symbol]
+  # @return [Hash]
+  def section(node, name)
+    key = node.key?(name.to_s) ? name.to_s : name
+    node[key] ||= {}
+  end
 end
 
 if ENV['OPENAPI']

From a2354df19d1971468502d03e101635b52fc6aa54 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sat, 19 Sep 2026 22:45:08 +0200
Subject: [PATCH 010/108] fix(api): require access token on studio validate

POST /api/v1/feeds/validate was the only studio operation reachable without a
token. Preview and suggest both call `Auth.authenticate` and raise
`UnauthorizedError`, so an unauthenticated caller could still drive the schema
validator, the YAML parser and the refined-selectors allowlist -- CPU the
instance owner never granted, and a free oracle for which config shapes the
instance accepts.

Gate it the same way its siblings are gated. Validate needs no live fetch, so
it takes the token check only, not the auto-source flag or the per-account URL
allowlist.

The request spec posted with no Authorization header and asserted 200; it now
carries the admin token, and the shared api-error-contract example covers the
401. Regenerated `public/openapi.yaml` and the frontend client so
validateFeedConfig declares bearer security and its 401 response, which also
clears the last Redocly `security-defined` error under `make openapi-lint`.
---
 app/web/api/v1/validate_config.rb       |  6 ++--
 frontend/src/api/generated/sdk.gen.ts   |  5 +--
 frontend/src/api/generated/types.gen.ts | 17 ++++++++++
 public/openapi.yaml                     | 42 +++++++++++++++++++++++++
 spec/html2rss/web/api/v1_spec.rb        | 20 +++++++++++-
 5 files changed, 85 insertions(+), 5 deletions(-)

diff --git a/app/web/api/v1/validate_config.rb b/app/web/api/v1/validate_config.rb
index c932c371..d1a3ef38 100644
--- a/app/web/api/v1/validate_config.rb
+++ b/app/web/api/v1/validate_config.rb
@@ -20,7 +20,7 @@ class << self
             # @param request [Rack::Request]
             # @return [Hash{Symbol=>Object}]
             def call(request)
-              ensure_enabled!
+              ensure_allowed!(request)
               body = json_object(request)
               report, selectors = assess(body)
               Response.success(response: request.response, data: payload(report, selectors))
@@ -28,9 +28,11 @@ def call(request)
 
             private
 
+            # @param request [Rack::Request]
             # @return [void]
-            def ensure_enabled!
+            def ensure_allowed!(request)
               raise ForbiddenError, 'Studio is disabled' unless Flags.studio_enabled?
+              raise UnauthorizedError, 'Authentication required' unless Auth.authenticate(request)
             end
 
             # @param request [Rack::Request]
diff --git a/frontend/src/api/generated/sdk.gen.ts b/frontend/src/api/generated/sdk.gen.ts
index ca91cce0..53308194 100644
--- a/frontend/src/api/generated/sdk.gen.ts
+++ b/frontend/src/api/generated/sdk.gen.ts
@@ -97,12 +97,13 @@ export const suggestSelectors = <ThrowOnError extends boolean = false>(options:
  *
  * Validate a refined config
  */
-export const validateFeedConfig = <ThrowOnError extends boolean = false>(options?: Options<ValidateFeedConfigData, ThrowOnError>): RequestResult<ValidateFeedConfigResponses, ValidateFeedConfigErrors, ThrowOnError> => (options?.client ?? client).post<ValidateFeedConfigResponses, ValidateFeedConfigErrors, ThrowOnError>({
+export const validateFeedConfig = <ThrowOnError extends boolean = false>(options: Options<ValidateFeedConfigData, ThrowOnError>): RequestResult<ValidateFeedConfigResponses, ValidateFeedConfigErrors, ThrowOnError> => (options.client ?? client).post<ValidateFeedConfigResponses, ValidateFeedConfigErrors, ThrowOnError>({
+  security: [{ scheme: 'bearer', type: 'http' }],
   url: '/feeds/validate',
   ...options,
   headers: {
     'Content-Type': 'application/json',
-    ...options?.headers
+    ...options.headers
   }
 });
 
diff --git a/frontend/src/api/generated/types.gen.ts b/frontend/src/api/generated/types.gen.ts
index b3ba6927..b2ea3071 100644
--- a/frontend/src/api/generated/types.gen.ts
+++ b/frontend/src/api/generated/types.gen.ts
@@ -347,6 +347,9 @@ export type ValidateFeedConfigData = {
     };
     yaml?: string;
   };
+  headers: {
+    Authorization: string;
+  };
   path?: never;
   query?: never;
   url: '/feeds/validate';
@@ -367,6 +370,20 @@ export type ValidateFeedConfigErrors = {
     };
     success: boolean;
   };
+  /**
+   * returns 401 with UNAUTHORIZED error payload
+   */
+  401: {
+    error: {
+      code: string;
+      kind: string;
+      message: string;
+      next_action: string;
+      retry_action: string;
+      retryable: boolean;
+    };
+    success: boolean;
+  };
 };
 
 export type ValidateFeedConfigError = ValidateFeedConfigErrors[keyof ValidateFeedConfigErrors];
diff --git a/public/openapi.yaml b/public/openapi.yaml
index 37afe559..1cd05169 100644
--- a/public/openapi.yaml
+++ b/public/openapi.yaml
@@ -718,6 +718,12 @@ paths:
     post:
       description: Validate a refined config
       operationId: validateFeedConfig
+      parameters:
+      - in: header
+        name: Authorization
+        required: true
+        schema:
+          type: string
       requestBody:
         content:
           application/json:
@@ -854,6 +860,42 @@ paths:
                 - error
                 type: object
           description: rejects channel so the token url cannot be replaced
+        '401':
+          content:
+            application/json:
+              schema:
+                properties:
+                  error:
+                    properties:
+                      code:
+                        type: string
+                      kind:
+                        type: string
+                      message:
+                        type: string
+                      next_action:
+                        type: string
+                      retry_action:
+                        type: string
+                      retryable:
+                        type: boolean
+                    required:
+                    - code
+                    - message
+                    - kind
+                    - retryable
+                    - next_action
+                    - retry_action
+                    type: object
+                  success:
+                    type: boolean
+                required:
+                - success
+                - error
+                type: object
+          description: returns 401 with UNAUTHORIZED error payload
+      security:
+      - BearerAuth: []
       summary: Validate a refined config
       tags:
       - Studio
diff --git a/spec/html2rss/web/api/v1_spec.rb b/spec/html2rss/web/api/v1_spec.rb
index ba4f48d8..2bb97936 100644
--- a/spec/html2rss/web/api/v1_spec.rb
+++ b/spec/html2rss/web/api/v1_spec.rb
@@ -844,13 +844,31 @@ def relative_feed_link_header(token)
   describe 'POST /api/v1/feeds/validate', openapi: {
     summary: 'Validate a refined config',
     operation_id: 'validateFeedConfig',
-    tags: ['Studio']
+    tags: ['Studio'],
+    security: [{ 'BearerAuth' => [] }]
   } do
     def post_validate(payload)
+      header 'Authorization', "Bearer #{admin_token}"
       header 'Content-Type', 'application/json'
       post '/api/v1/feeds/validate', payload.to_json
     end
 
+    let(:perform_request) do
+      lambda {
+        header 'Content-Type', 'application/json'
+        post '/api/v1/feeds/validate', { selectors: { items: { selector: 'article' } } }.to_json
+      }
+    end
+
+    it_behaves_like 'api error contract', {
+      status: 401,
+      code: Html2rss::Web::UnauthorizedError::CODE,
+      kind: 'auth',
+      retryable: false,
+      next_action: 'enter_token',
+      retry_action: 'none'
+    }
+
     it 'returns a structured report for an allowlisted selectors object', :aggregate_failures do
       post_validate(selectors: { items: { selector: 'article', enhance: true } })
 

From e378a2a96310f95c790b55b3b4503f808f4c13f7 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sat, 19 Sep 2026 22:48:28 +0200
Subject: [PATCH 011/108] docs: document STUDIO_ENABLED and cover the disabled
 path

`STUDIO_ENABLED` existed only in app/web/config/flags.rb, so an operator had
to read the flag registry to learn the studio endpoints exist, that they are
off in production, or how to turn them on. Document it next to
`AUTO_SOURCE_ENABLED` in the docs flag table, .env.example, and the production
compose file (the quickstart compose is left alone: RACK_ENV=development
already defaults the flag on, and it lists only what it must set).

State what the flag exposes rather than just naming it: validate, preview and
suggest_selectors; all token-gated; 403 "Studio is disabled" when off; preview
and suggest_selectors additionally require AUTO_SOURCE_ENABLED because they
fetch the caller's URL live and are bounded by the account URL allowlist.

The 403 branch had no request coverage. The new examples iterate
`FeedRoutes::STUDIO_POSTS`, so a future studio endpoint is covered by the same
gate instead of silently shipping without one. They are `openapi: false`: the
flag-off shape is an operator concern, and the other ClimateControl-driven
examples in this file stay out of the published contract too.
---
 .env.example                     |  6 ++++++
 docker-compose.yml               |  2 ++
 docs/README.md                   |  3 +++
 spec/html2rss/web/api/v1_spec.rb | 17 +++++++++++++++++
 4 files changed, 28 insertions(+)

diff --git a/.env.example b/.env.example
index 4b6523ef..589bc727 100644
--- a/.env.example
+++ b/.env.example
@@ -17,6 +17,12 @@ HTML2RSS_ACCESS_TOKEN=
 # Keep enabled to allow pasting any webpage URL to generate an RSS feed.
 AUTO_SOURCE_ENABLED=true
 
+# OPTIONAL: Config refinement studio (off in production unless set to true).
+# Exposes POST /api/v1/feeds/validate, /preview and /suggest_selectors. All three
+# require HTML2RSS_ACCESS_TOKEN; preview and suggest_selectors also fetch the
+# submitted URL live and need AUTO_SOURCE_ENABLED=true.
+# STUDIO_ENABLED=false
+
 # COMPANION SCRAPER:
 # URL of the companion Botasaurus scraper API service in docker-compose.
 BOTASAURUS_SCRAPER_URL=http://botasaurus:4010
diff --git a/docker-compose.yml b/docker-compose.yml
index 2590d937..703d6356 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -23,6 +23,8 @@ services:
       HTML2RSS_SECRET_KEY: ${HTML2RSS_SECRET_KEY:?set HTML2RSS_SECRET_KEY in .env (generate with `openssl rand -hex 32`)}
       HTML2RSS_ACCESS_TOKEN: ${HTML2RSS_ACCESS_TOKEN:?set HTML2RSS_ACCESS_TOKEN in .env (generate with `openssl rand -hex 32`)}
       AUTO_SOURCE_ENABLED: ${AUTO_SOURCE_ENABLED:-true}
+      # Config refinement studio (validate/preview/suggest_selectors); token-gated, off by default.
+      STUDIO_ENABLED: ${STUDIO_ENABLED:-false}
       HEALTH_CHECK_TOKEN: ${HEALTH_CHECK_TOKEN:-}
       # Web Sentry (Project A): SENTRY_DSN; logs opt-in via SENTRY_ENABLE_LOGS=true
       SENTRY_DSN: ${SENTRY_DSN:-}
diff --git a/docs/README.md b/docs/README.md
index fb3f4cd2..32439dcd 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -192,6 +192,7 @@ Managed flags and environment keys:
 | Name                              | Env key                           | Type           | Default                                  |
 | --------------------------------- | --------------------------------- | -------------- | ---------------------------------------- |
 | `auto_source_enabled`             | `AUTO_SOURCE_ENABLED`             | boolean        | `true` in development/test, else `false` |
+| `studio_enabled`                  | `STUDIO_ENABLED`                  | boolean        | `true` in development/test, else `false` |
 | `health_check_token`              | `HEALTH_CHECK_TOKEN`              | string         | `nil`                                    |
 | `build_tag`                       | `BUILD_TAG`                       | string         | `unknown` outside production             |
 | `git_sha`                         | `GIT_SHA`                         | string         | `unknown` outside production             |
@@ -206,6 +207,8 @@ Rules:
 - `BUILD_TAG` and `GIT_SHA` are required in production so startup logs can identify the deployed build.
 - Add or change flags in code, tests, and this table together.
 
+`STUDIO_ENABLED=true` exposes the config refinement studio: `POST /api/v1/feeds/validate`, `POST /api/v1/feeds/preview`, and `POST /api/v1/feeds/suggest_selectors`. All three require a valid access token and return `403 Studio is disabled` when the flag is off. `preview` and `suggest_selectors` additionally need `AUTO_SOURCE_ENABLED=true` because they fetch the caller's URL live, and they only accept URLs the caller's account is allowed to reach. Leave the flag off in production unless you intend to let token holders run live extraction against arbitrary allowed URLs.
+
 ---
 
 ## Observability Contract
diff --git a/spec/html2rss/web/api/v1_spec.rb b/spec/html2rss/web/api/v1_spec.rb
index 2bb97936..2bc274b4 100644
--- a/spec/html2rss/web/api/v1_spec.rb
+++ b/spec/html2rss/web/api/v1_spec.rb
@@ -984,4 +984,21 @@ def post_validate(payload)
       expect(json.dig('data', 'enhance')).to be(false)
     end
   end
+
+  describe 'studio POSTs with STUDIO_ENABLED=false', openapi: false do
+    around do |example|
+      ClimateControl.modify(STUDIO_ENABLED: 'false') { example.run }
+    end
+
+    Html2rss::Web::Routes::ApiV1::FeedRoutes::STUDIO_POSTS.each_key do |path|
+      it "returns 403 for POST /api/v1/feeds/#{path}", :aggregate_failures do
+        header 'Authorization', "Bearer #{admin_token}"
+        header 'Content-Type', 'application/json'
+        post "/api/v1/feeds/#{path}", { url: feed_url, selectors: { items: { selector: 'article' } } }.to_json
+
+        expect(last_response.status).to eq(403)
+        expect(JSON.parse(last_response.body).dig('error', 'message')).to eq('Studio is disabled')
+      end
+    end
+  end
 end

From 9c85f70ead5fe391ed1c80a6e546f8736634d66e Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sat, 19 Sep 2026 23:04:59 +0200
Subject: [PATCH 012/108] feat(frontend): add studio transport and refinement
 state hook

Unwrap the studio envelope in one service and keep refinement phase, issues, and preview in a discriminated union so later panels cannot invent a second client.
---
 frontend/src/__tests__/mocks/server.ts   |  33 ++
 frontend/src/__tests__/useStudio.test.ts | 288 ++++++++++++++
 frontend/src/studio/selectorDraft.ts     | 476 +++++++++++++++++++++++
 frontend/src/studio/studioService.ts     | 274 +++++++++++++
 frontend/src/studio/useStudio.ts         | 283 ++++++++++++++
 5 files changed, 1354 insertions(+)
 create mode 100644 frontend/src/__tests__/useStudio.test.ts
 create mode 100644 frontend/src/studio/selectorDraft.ts
 create mode 100644 frontend/src/studio/studioService.ts
 create mode 100644 frontend/src/studio/useStudio.ts

diff --git a/frontend/src/__tests__/mocks/server.ts b/frontend/src/__tests__/mocks/server.ts
index 87a10337..632d098d 100644
--- a/frontend/src/__tests__/mocks/server.ts
+++ b/frontend/src/__tests__/mocks/server.ts
@@ -30,6 +30,39 @@ export const server = setupServer(
       data: { configs: [] },
       meta: { total: 0, catalog_version: 2, starters: [] },
     });
+  }),
+  http.post('/api/v1/feeds/validate', () => {
+    return HttpResponse.json({
+      success: true,
+      data: {
+        report: { success: true, issues: [] },
+        selectors: { items: { selector: 'article', enhance: false } },
+        yaml: 'selectors:\n  items:\n    selector: article\n    enhance: false\n',
+      },
+    });
+  }),
+  http.post('/api/v1/feeds/preview', () => {
+    return HttpResponse.json({
+      success: true,
+      data: {
+        item_count: 0,
+        sample_items: [],
+        quality_report: { warnings: [], metrics: { short_title_count: 0 } },
+        failure_kind: '',
+        validation_issues: [],
+      },
+    });
+  }),
+  http.post('/api/v1/feeds/suggest_selectors', () => {
+    return HttpResponse.json({
+      success: true,
+      data: {
+        selectors: { items: { selector: 'article', enhance: true } },
+        segment_strategy: 'list',
+        admission_drops: { chrome: 0 },
+        enhance: true,
+      },
+    });
   })
 );
 
diff --git a/frontend/src/__tests__/useStudio.test.ts b/frontend/src/__tests__/useStudio.test.ts
new file mode 100644
index 00000000..6643ee35
--- /dev/null
+++ b/frontend/src/__tests__/useStudio.test.ts
@@ -0,0 +1,288 @@
+import { describe, it, expect, beforeEach, afterEach, vi, type SpyInstance } from 'vitest';
+import { renderHook, act, waitFor } from '@testing-library/preact';
+import { draftFromSelectors, selectorsFromDraft } from '../studio/selectorDraft';
+import { STUDIO_VALIDATE_DELAY_MS, useStudio } from '../studio/useStudio';
+
+const pageUrl = 'https://example.com/articles';
+const token = 'studio-token';
+const wireNull: unknown = JSON.parse('null');
+
+function validateBody(overrides: Record<string, unknown> = {}) {
+  return {
+    success: true,
+    data: {
+      report: { success: true, issues: [] },
+      selectors: { items: { selector: 'article', enhance: false } },
+      yaml: 'selectors:\n  items:\n    selector: article\n',
+      ...overrides,
+    },
+  };
+}
+
+describe('selector draft', () => {
+  it('keeps attribute selectors, post-processors, and untouched keys', () => {
+    const draft = draftFromSelectors({
+      items: { selector: 'article', enhance: true, order: 'reverse' },
+      title: {
+        selector: 'h2',
+        extractor: 'text',
+        post_process: [{ name: 'gsub', pattern: 'a', replacement: 'b' }],
+      },
+      guid: ['title'],
+    });
+
+    expect(draft?.itemsSelector).toBe('article');
+    expect(draft?.enhance).toBe(true);
+    expect(draft?.itemsPreserved).toEqual({ order: 'reverse' });
+    expect(draft?.attributes[0]).toMatchObject({
+      name: 'title',
+      selector: 'h2',
+      extractor: 'text',
+    });
+    expect(draft?.attributes[0]?.postProcessors[0]).toMatchObject({
+      name: 'gsub',
+      pattern: 'a',
+      replacement: 'b',
+    });
+
+    expect(draft).toBeDefined();
+    if (!draft) return;
+
+    expect(selectorsFromDraft(draft)).toEqual({
+      items: { selector: 'article', enhance: true, order: 'reverse' },
+      title: {
+        selector: 'h2',
+        extractor: 'text',
+        post_process: [{ name: 'gsub', pattern: 'a', replacement: 'b' }],
+      },
+      guid: ['title'],
+    });
+  });
+});
+
+describe('useStudio', () => {
+  let fetchMock: SpyInstance;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    fetchMock = vi.spyOn(globalThis, 'fetch');
+  });
+
+  afterEach(() => {
+    fetchMock.mockRestore();
+    vi.useRealTimers();
+  });
+
+  it('waits 300ms, sends the bearer token, and unwraps a valid report', async () => {
+    vi.useFakeTimers();
+    fetchMock.mockResolvedValue(Response.json(validateBody()));
+
+    const { result } = renderHook(() => useStudio({ url: pageUrl, token }));
+    expect(fetchMock).not.toHaveBeenCalled();
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(STUDIO_VALIDATE_DELAY_MS - 1);
+    });
+    expect(fetchMock).not.toHaveBeenCalled();
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(1);
+    });
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(fetchMock.mock.calls[0]?.[0]).toBe('/api/v1/feeds/validate');
+    const init = fetchMock.mock.calls[0]?.[1];
+    expect(init?.headers).toMatchObject({ Authorization: `Bearer ${token}` });
+    expect(JSON.parse(String(init?.body))).toEqual({
+      selectors: { items: { enhance: false } },
+    });
+
+    const state = result.current.state;
+    expect(state.phase).toBe('editing');
+    if (state.phase !== 'editing') return;
+    expect(state.validated).toBe(true);
+    expect(state.yaml).toContain('article');
+    expect(state.draft.itemsSelector).toBe('article');
+  });
+
+  it('keeps returned issue codes on the invalid phase', async () => {
+    fetchMock.mockResolvedValue(
+      Response.json(
+        validateBody({
+          report: {
+            success: false,
+            issues: [
+              {
+                path: ['selectors', 'items', 'selector'],
+                code: 'missing_key',
+                message: 'is missing',
+              },
+            ],
+          },
+          selectors: { items: { enhance: false } },
+          yaml: wireNull,
+        })
+      )
+    );
+
+    const { result } = renderHook(() => useStudio({ url: pageUrl, token, validateDelayMs: 0 }));
+    await waitFor(() => expect(result.current.state.phase).toBe('invalid'));
+
+    const state = result.current.state;
+    if (state.phase !== 'invalid') return;
+    expect(state.issues).toEqual([
+      {
+        path: ['selectors', 'items', 'selector'],
+        code: 'missing_key',
+        message: 'is missing',
+      },
+    ]);
+  });
+
+  it('freezes builder hydration while yaml does not parse', async () => {
+    fetchMock.mockResolvedValueOnce(Response.json(validateBody())).mockResolvedValueOnce(
+      Response.json(
+        validateBody({
+          report: {
+            success: false,
+            issues: [
+              {
+                path: [],
+                code: 'parse',
+                message: 'could not parse',
+              },
+            ],
+          },
+          selectors: wireNull,
+          yaml: wireNull,
+        })
+      )
+    );
+
+    const { result } = renderHook(() => useStudio({ url: pageUrl, token, validateDelayMs: 0 }));
+    await waitFor(() => {
+      expect(result.current.state.phase).toBe('editing');
+      expect(result.current.state.draft.itemsSelector).toBe('article');
+    });
+
+    act(() => {
+      result.current.setYaml(':');
+    });
+
+    await waitFor(() => expect(result.current.state.phase).toBe('invalid'));
+    const state = result.current.state;
+    if (state.phase !== 'invalid') return;
+    expect(state.issues[0]?.code).toBe('parse');
+    expect(state.draft.itemsSelector).toBe('article');
+    expect(state.yaml).toBe(':');
+    expect(JSON.parse(String(fetchMock.mock.calls[1]?.[1]?.body))).toEqual({ yaml: ':' });
+  });
+
+  it('moves to previewed after a preview response', async () => {
+    fetchMock.mockImplementation((input: RequestInfo | URL) => {
+      const path = String(input);
+      if (path.endsWith('/feeds/preview')) {
+        return Promise.resolve(
+          Response.json({
+            success: true,
+            data: {
+              item_count: 1,
+              sample_items: [{ title: 'Sample' }],
+              quality_report: { warnings: ['short title'], metrics: { short_title_count: 1 } },
+              failure_kind: wireNull,
+              validation_issues: [],
+            },
+          })
+        );
+      }
+
+      return Promise.resolve(Response.json(validateBody()));
+    });
+
+    const { result } = renderHook(() => useStudio({ url: pageUrl, token, validateDelayMs: 0 }));
+    await waitFor(() => {
+      const state = result.current.state;
+      expect(state.phase === 'editing' && state.validated).toBe(true);
+    });
+
+    act(() => {
+      result.current.requestPreview();
+    });
+
+    await waitFor(() => expect(result.current.state.phase).toBe('previewed'));
+    const state = result.current.state;
+    if (state.phase !== 'previewed') return;
+    expect(state.preview).toEqual({
+      itemCount: 1,
+      titles: ['Sample'],
+      warnings: ['short title'],
+      failureKind: undefined,
+    });
+  });
+
+  it('applies one capture suggestion onto the items selector', async () => {
+    fetchMock.mockImplementation(async (input: RequestInfo | URL, init?: RequestInit) => {
+      if (String(input).endsWith('/feeds/suggest_selectors')) {
+        return Response.json({
+          success: true,
+          data: {
+            selectors: { items: { selector: '.post', enhance: true } },
+            segment_strategy: 'list',
+            admission_drops: { chrome: 2 },
+            enhance: true,
+          },
+        });
+      }
+
+      const parsed: unknown = JSON.parse(String(init?.body));
+      const selectors =
+        typeof parsed === 'object' && parsed && 'selectors' in parsed ? parsed.selectors : undefined;
+      return Response.json(
+        validateBody({
+          selectors: selectors ?? { items: { selector: 'article', enhance: false } },
+        })
+      );
+    });
+
+    const { result } = renderHook(() => useStudio({ url: pageUrl, token, validateDelayMs: 0 }));
+    await waitFor(() => expect(result.current.state.phase).toBe('editing'));
+
+    act(() => {
+      result.current.requestSuggestion();
+    });
+
+    await waitFor(() => expect(result.current.state.draft.itemsSelector).toBe('.post'));
+    expect(result.current.state.draft.enhance).toBe(true);
+    expect(result.current.suggestion).toEqual({
+      itemsSelector: '.post',
+      enhance: true,
+      segmentStrategy: 'list',
+      chromeDrops: 2,
+    });
+  });
+
+  it('fails closed when validate is unauthorized', async () => {
+    fetchMock.mockResolvedValue(
+      Response.json(
+        {
+          success: false,
+          error: {
+            code: 'UNAUTHORIZED',
+            message: 'Authentication required',
+            kind: 'auth',
+            retryable: false,
+            next_action: 'enter_token',
+            retry_action: 'none',
+          },
+        },
+        { status: 401 }
+      )
+    );
+
+    const { result } = renderHook(() => useStudio({ url: pageUrl, token, validateDelayMs: 0 }));
+    await waitFor(() => expect(result.current.state.phase).toBe('failed'));
+    const state = result.current.state;
+    if (state.phase !== 'failed') return;
+    expect(state.message).toBe('Authentication required');
+  });
+});
diff --git a/frontend/src/studio/selectorDraft.ts b/frontend/src/studio/selectorDraft.ts
new file mode 100644
index 00000000..25c741c7
--- /dev/null
+++ b/frontend/src/studio/selectorDraft.ts
@@ -0,0 +1,476 @@
+/**
+ * Visual-builder draft for an allowlisted selectors document.
+ *
+ * The generated client types `selectors.items` only, because the published
+ * examples collapse `patternProperties`. This module owns the gem selector
+ * document the builder edits. It is not a second copy of the issue schema.
+ */
+
+function closed<const T extends readonly string[]>(values: T): T {
+  return values;
+}
+
+export const EXTRACTOR_NAMES = closed(['text', 'attribute', 'href', 'html', 'static']);
+export type ExtractorName = (typeof EXTRACTOR_NAMES)[number];
+
+export const POST_PROCESSOR_NAMES = closed([
+  'gsub',
+  'markdown_to_html',
+  'parse_time',
+  'parse_uri',
+  'sanitize_html',
+  'substring',
+  'template',
+]);
+export type PostProcessorName = (typeof POST_PROCESSOR_NAMES)[number];
+
+export type PostProcessorDraft =
+  | { readonly id: string; readonly name: 'gsub'; readonly pattern: string; readonly replacement: string }
+  | { readonly id: string; readonly name: 'substring'; readonly start: string; readonly end: string }
+  | { readonly id: string; readonly name: 'template'; readonly template: string }
+  | {
+      readonly id: string;
+      readonly name: 'markdown_to_html' | 'parse_time' | 'parse_uri' | 'sanitize_html';
+    }
+  | { readonly id: string; readonly name: 'unrecognized'; readonly raw: Readonly<Record<string, unknown>> };
+
+export interface AttributeDraft {
+  readonly id: string;
+  readonly name: string;
+  readonly selector: string;
+  readonly extractor: ExtractorName;
+  readonly attributeName: string;
+  readonly staticValue: string;
+  readonly postProcessors: readonly PostProcessorDraft[];
+  readonly preserved: Readonly<Record<string, unknown>>;
+}
+
+export interface StudioDraft {
+  readonly itemsSelector: string;
+  readonly enhance: boolean;
+  readonly attributes: readonly AttributeDraft[];
+  readonly preserved: Readonly<Record<string, unknown>>;
+  readonly itemsPreserved: Readonly<Record<string, unknown>>;
+}
+
+export interface AttributePatch {
+  readonly name?: string;
+  readonly selector?: string;
+  readonly extractor?: ExtractorName;
+  readonly attributeName?: string;
+  readonly staticValue?: string;
+}
+
+export function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return (
+    typeof value === 'object' && value instanceof Object && Object.getPrototypeOf(value) === Object.prototype
+  );
+}
+
+const mintDraftId = (() => {
+  let nextDraftId = 0;
+  return (prefix: string): string => {
+    nextDraftId += 1;
+    return `${prefix}-${nextDraftId}`;
+  };
+})();
+
+export function emptyDraft(): StudioDraft {
+  return {
+    itemsSelector: '',
+    enhance: false,
+    attributes: [],
+    preserved: {},
+    itemsPreserved: {},
+  };
+}
+
+export function selectorsFromDraft(draft: StudioDraft): Record<string, unknown> {
+  const names = draft.attributes.map((attribute) => attribute.name.trim()).filter((name) => name.length > 0);
+  const selectors = withoutKeys(draft.preserved, ['items', ...names]);
+  const items: Record<string, unknown> = { ...draft.itemsPreserved, enhance: draft.enhance };
+  if (draft.itemsSelector.length > 0) items.selector = draft.itemsSelector;
+  selectors.items = items;
+
+  for (const attribute of draft.attributes) {
+    const name = attribute.name.trim();
+    if (!name) continue;
+    selectors[name] = attributeToWire(attribute);
+  }
+
+  return selectors;
+}
+
+export function draftFromSelectors(value: unknown): StudioDraft | undefined {
+  if (!isPlainRecord(value)) return;
+
+  const items = isPlainRecord(value.items) ? value.items : undefined;
+  const attributes: AttributeDraft[] = [];
+  const preserved: Record<string, unknown> = {};
+
+  for (const [key, nested] of Object.entries(value)) {
+    if (key === 'items') continue;
+    const attribute = parseAttribute(key, nested);
+    if (attribute) {
+      attributes.push(attribute);
+    } else {
+      preserved[key] = nested;
+    }
+  }
+
+  return {
+    itemsSelector: typeof items?.selector === 'string' ? items.selector : '',
+    enhance: items?.enhance === true,
+    attributes,
+    preserved,
+    itemsPreserved: items ? withoutKeys(items, ['selector', 'enhance']) : {},
+  };
+}
+
+export function withItemsSelector(draft: StudioDraft, itemsSelector: string): StudioDraft {
+  return { ...draft, itemsSelector };
+}
+
+export function withEnhance(draft: StudioDraft, isEnhanced: boolean): StudioDraft {
+  return { ...draft, enhance: isEnhanced };
+}
+
+export function addAttribute(draft: StudioDraft): StudioDraft {
+  return { ...draft, attributes: [...draft.attributes, blankAttribute()] };
+}
+
+export function updateAttribute(draft: StudioDraft, attributeId: string, patch: AttributePatch): StudioDraft {
+  return mapAttributes(draft, (attribute) => {
+    if (attribute.id !== attributeId) return attribute;
+    return {
+      ...attribute,
+      name: patch.name ?? attribute.name,
+      selector: patch.selector ?? attribute.selector,
+      extractor: patch.extractor ?? attribute.extractor,
+      attributeName: patch.attributeName ?? attribute.attributeName,
+      staticValue: patch.staticValue ?? attribute.staticValue,
+    };
+  });
+}
+
+export function removeAttribute(draft: StudioDraft, attributeId: string): StudioDraft {
+  return {
+    ...draft,
+    attributes: draft.attributes.filter((attribute) => attribute.id !== attributeId),
+  };
+}
+
+export function addPostProcessor(draft: StudioDraft, attributeId: string): StudioDraft {
+  return mapAttributes(draft, (attribute) => {
+    if (attribute.id !== attributeId) return attribute;
+    return {
+      ...attribute,
+      postProcessors: [
+        ...attribute.postProcessors,
+        blankProcessor('sanitize_html', mintDraftId('processor')),
+      ],
+    };
+  });
+}
+
+export function removePostProcessor(
+  draft: StudioDraft,
+  attributeId: string,
+  processorId: string
+): StudioDraft {
+  return mapAttributes(draft, (attribute) => {
+    if (attribute.id !== attributeId) return attribute;
+    return {
+      ...attribute,
+      postProcessors: attribute.postProcessors.filter((processor) => processor.id !== processorId),
+    };
+  });
+}
+
+export function renamePostProcessor(
+  draft: StudioDraft,
+  attributeId: string,
+  processorId: string,
+  name: PostProcessorName
+): StudioDraft {
+  return mapAttributes(draft, (attribute) => {
+    if (attribute.id !== attributeId) return attribute;
+    return {
+      ...attribute,
+      postProcessors: attribute.postProcessors.map((processor) =>
+        processor.id === processorId ? blankProcessor(name, processor.id) : processor
+      ),
+    };
+  });
+}
+
+export type PostProcessorField = 'pattern' | 'replacement' | 'start' | 'end' | 'template';
+
+export function updatePostProcessorField(
+  draft: StudioDraft,
+  attributeId: string,
+  processorId: string,
+  field: PostProcessorField,
+  value: string
+): StudioDraft {
+  return mapAttributes(draft, (attribute) => {
+    if (attribute.id !== attributeId) return attribute;
+    return {
+      ...attribute,
+      postProcessors: attribute.postProcessors.map((processor) =>
+        processor.id === processorId ? applyProcessorField(processor, field, value) : processor
+      ),
+    };
+  });
+}
+
+export function applyItemsSuggestion(
+  draft: StudioDraft,
+  itemsSelector: string,
+  isEnhanced: boolean
+): StudioDraft {
+  return { ...draft, itemsSelector, enhance: isEnhanced };
+}
+
+export function reuseDraftIds(
+  previous: StudioDraft,
+  incoming: StudioDraft,
+  shouldKeepBlankAttributes: boolean
+): StudioDraft {
+  const previousByName = new Map(previous.attributes.map((attribute) => [attribute.name, attribute]));
+  const attributes = incoming.attributes.map((attribute) =>
+    reuseAttributeId(attribute, previousByName.get(attribute.name))
+  );
+  const blanks = shouldKeepBlankAttributes
+    ? previous.attributes.filter((attribute) => attribute.name.trim() === '')
+    : [];
+
+  return { ...incoming, attributes: [...attributes, ...blanks] };
+}
+
+function reuseAttributeId(attribute: AttributeDraft, prior: AttributeDraft | undefined): AttributeDraft {
+  if (!prior) return attribute;
+  return {
+    ...attribute,
+    id: prior.id,
+    postProcessors: attribute.postProcessors.map((processor, index) =>
+      withProcessorId(processor, prior.postProcessors[index]?.id ?? processor.id)
+    ),
+  };
+}
+
+function withProcessorId(processor: PostProcessorDraft, id: string): PostProcessorDraft {
+  switch (processor.name) {
+    case 'gsub':
+    case 'substring':
+    case 'template':
+    case 'markdown_to_html':
+    case 'parse_time':
+    case 'parse_uri':
+    case 'sanitize_html':
+    case 'unrecognized': {
+      return { ...processor, id };
+    }
+  }
+}
+
+function applyProcessorField(
+  processor: PostProcessorDraft,
+  field: PostProcessorField,
+  value: string
+): PostProcessorDraft {
+  switch (processor.name) {
+    case 'gsub': {
+      if (field === 'pattern') return { ...processor, pattern: value };
+      if (field === 'replacement') return { ...processor, replacement: value };
+      return processor;
+    }
+    case 'substring': {
+      if (field === 'start') return { ...processor, start: value };
+      if (field === 'end') return { ...processor, end: value };
+      return processor;
+    }
+    case 'template': {
+      if (field === 'template') return { ...processor, template: value };
+      return processor;
+    }
+    default: {
+      return processor;
+    }
+  }
+}
+
+function blankAttribute(): AttributeDraft {
+  return {
+    id: mintDraftId('attribute'),
+    name: '',
+    selector: '',
+    extractor: 'text',
+    attributeName: '',
+    staticValue: '',
+    postProcessors: [],
+    preserved: {},
+  };
+}
+
+function blankProcessor(name: PostProcessorName, id: string): PostProcessorDraft {
+  switch (name) {
+    case 'gsub': {
+      return { id, name, pattern: '', replacement: '' };
+    }
+    case 'substring': {
+      return { id, name, start: '', end: '' };
+    }
+    case 'template': {
+      return { id, name, template: '' };
+    }
+    case 'markdown_to_html':
+    case 'parse_time':
+    case 'parse_uri':
+    case 'sanitize_html': {
+      return { id, name };
+    }
+  }
+}
+
+function mapAttributes(
+  draft: StudioDraft,
+  update: (attribute: AttributeDraft) => AttributeDraft
+): StudioDraft {
+  return { ...draft, attributes: draft.attributes.map((attribute) => update(attribute)) };
+}
+
+function attributeToWire(attribute: AttributeDraft): Record<string, unknown> {
+  const wire: Record<string, unknown> = {
+    ...attribute.preserved,
+    selector: attribute.selector,
+    extractor: attribute.extractor,
+  };
+  if (attribute.extractor === 'attribute') {
+    wire.attribute = attribute.attributeName;
+  } else if (attribute.extractor === 'static') {
+    wire.static = attribute.staticValue;
+  }
+  if (attribute.postProcessors.length > 0) {
+    wire.post_process = attribute.postProcessors.map((processor) => processorToWire(processor));
+  }
+  return wire;
+}
+
+function processorToWire(processor: PostProcessorDraft): Record<string, unknown> {
+  switch (processor.name) {
+    case 'gsub': {
+      return { name: 'gsub', pattern: processor.pattern, replacement: processor.replacement };
+    }
+    case 'substring': {
+      const wire: Record<string, unknown> = { name: 'substring' };
+      const start = integerField(processor.start);
+      if (start !== undefined) wire.start = start;
+      const end = integerField(processor.end);
+      if (end !== undefined) wire.end = end;
+      return wire;
+    }
+    case 'template': {
+      return { name: 'template', string: processor.template };
+    }
+    case 'markdown_to_html':
+    case 'parse_time':
+    case 'parse_uri':
+    case 'sanitize_html': {
+      return { name: processor.name };
+    }
+    case 'unrecognized': {
+      return { ...processor.raw };
+    }
+  }
+}
+
+function parseAttribute(name: string, value: unknown): AttributeDraft | undefined {
+  if (!isPlainRecord(value)) return;
+  const extractor = knownExtractor(value.extractor);
+  if (value.extractor !== undefined && !extractor) return;
+  if (value.post_process !== undefined && !Array.isArray(value.post_process)) return;
+
+  const postProcessors: PostProcessorDraft[] = [];
+  if (Array.isArray(value.post_process)) {
+    for (const item of value.post_process) {
+      const processor = parseProcessor(item);
+      if (!processor) return;
+      postProcessors.push(processor);
+    }
+  }
+
+  return {
+    id: mintDraftId('attribute'),
+    name,
+    selector: typeof value.selector === 'string' ? value.selector : '',
+    extractor: extractor ?? 'text',
+    attributeName: typeof value.attribute === 'string' ? value.attribute : '',
+    staticValue: typeof value.static === 'string' ? value.static : '',
+    postProcessors,
+    preserved: withoutKeys(value, ['selector', 'extractor', 'attribute', 'static', 'post_process']),
+  };
+}
+
+function parseProcessor(value: unknown): PostProcessorDraft | undefined {
+  if (!isPlainRecord(value) || typeof value.name !== 'string') return;
+  const id = mintDraftId('processor');
+  switch (value.name) {
+    case 'gsub': {
+      if (typeof value.pattern !== 'string' || typeof value.replacement !== 'string') {
+        return { id, name: 'unrecognized', raw: { ...value } };
+      }
+      return { id, name: 'gsub', pattern: value.pattern, replacement: value.replacement };
+    }
+    case 'substring': {
+      return {
+        id,
+        name: 'substring',
+        start: integerText(value.start),
+        end: integerText(value.end),
+      };
+    }
+    case 'template': {
+      if (typeof value.string !== 'string') return { id, name: 'unrecognized', raw: { ...value } };
+      return { id, name: 'template', template: value.string };
+    }
+    case 'markdown_to_html':
+    case 'parse_time':
+    case 'parse_uri':
+    case 'sanitize_html': {
+      return { id, name: value.name };
+    }
+    default: {
+      return { id, name: 'unrecognized', raw: { ...value } };
+    }
+  }
+}
+
+function knownExtractor(value: unknown): ExtractorName | undefined {
+  if (typeof value !== 'string') return;
+  for (const name of EXTRACTOR_NAMES) {
+    if (name === value) return name;
+  }
+  return;
+}
+
+function withoutKeys(
+  value: Readonly<Record<string, unknown>>,
+  keys: readonly string[]
+): Record<string, unknown> {
+  const next: Record<string, unknown> = {};
+  for (const [key, nested] of Object.entries(value)) {
+    if (!keys.includes(key)) next[key] = nested;
+  }
+  return next;
+}
+
+function integerField(value: string): number | undefined {
+  if (!/^-?\d+$/.test(value)) return;
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) ? parsed : undefined;
+}
+
+function integerText(value: unknown): string {
+  return typeof value === 'number' && Number.isSafeInteger(value) ? String(value) : '';
+}
diff --git a/frontend/src/studio/studioService.ts b/frontend/src/studio/studioService.ts
new file mode 100644
index 00000000..85332cb6
--- /dev/null
+++ b/frontend/src/studio/studioService.ts
@@ -0,0 +1,274 @@
+/**
+ * Studio transport. The only place the `{ success, data }` envelope is unwrapped.
+ *
+ * Issue codes are the generated client's closed union. Selector documents are
+ * parsed into {@link StudioDraft} because the published selectors schema is the
+ * example shape (`items` only), not the allowlisted subtree.
+ */
+import type { ValidateFeedConfigResponses } from '../api/generated';
+import { COPY } from '../journey/copy';
+import { buildCreateHeaders, isAbortError, resolveApiUrl } from '../feeds/feedsService';
+import { draftFromSelectors, isPlainRecord, selectorsFromDraft, type StudioDraft } from './selectorDraft';
+
+type GeneratedIssue = ValidateFeedConfigResponses[200]['data']['report']['issues'][number];
+export type StudioIssueCode = GeneratedIssue['code'];
+
+export interface StudioIssue {
+  readonly path: readonly string[];
+  readonly code: StudioIssueCode;
+  readonly message: string;
+}
+
+export interface StudioValidationOutcome {
+  readonly valid: boolean;
+  readonly issues: readonly StudioIssue[];
+  readonly draft: StudioDraft | undefined;
+  readonly yaml: string | undefined;
+}
+
+export interface StudioPreview {
+  readonly itemCount: number;
+  readonly titles: readonly string[];
+  readonly warnings: readonly string[];
+  readonly failureKind: string | undefined;
+}
+
+export interface StudioSuggestion {
+  readonly itemsSelector: string;
+  readonly enhance: boolean;
+  readonly segmentStrategy: string;
+  readonly chromeDrops: number;
+}
+
+export class StudioRequestError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'StudioRequestError';
+  }
+}
+
+function listedIssueCodes<const T extends readonly StudioIssueCode[]>(
+  codes: [StudioIssueCode] extends [T[number]] ? T : never
+): T {
+  return codes;
+}
+
+const STUDIO_ISSUE_CODES = listedIssueCodes([
+  'constraint',
+  'invalid_value',
+  'missing_key',
+  'parse',
+  'type_mismatch',
+  'unknown_value',
+]);
+
+export function validateStudioSelectors(
+  token: string,
+  draft: StudioDraft,
+  signal?: AbortSignal
+): Promise<StudioValidationOutcome> {
+  return validateStudio(token, { selectors: selectorsFromDraft(draft) }, signal);
+}
+
+export function validateStudioYaml(
+  token: string,
+  yaml: string,
+  signal?: AbortSignal
+): Promise<StudioValidationOutcome> {
+  return validateStudio(token, { yaml }, signal);
+}
+
+export async function previewStudioFeed(
+  token: string,
+  url: string,
+  draft: StudioDraft,
+  signal?: AbortSignal
+): Promise<StudioPreview> {
+  const data = await postJson('feeds/preview', token, { url, selectors: selectorsFromDraft(draft) }, signal);
+  return parsePreview(data);
+}
+
+export async function suggestStudioSelectors(
+  token: string,
+  url: string,
+  itemsSelector: string,
+  signal?: AbortSignal
+): Promise<StudioSuggestion> {
+  const data = await postJson(
+    'feeds/suggest_selectors',
+    token,
+    { url, items_selector: itemsSelector },
+    signal
+  );
+  return parseSuggestion(data);
+}
+
+async function validateStudio(
+  token: string,
+  body: { readonly selectors: Record<string, unknown> } | { readonly yaml: string },
+  signal?: AbortSignal
+): Promise<StudioValidationOutcome> {
+  return parseValidation(await postJson('feeds/validate', token, body, signal));
+}
+
+async function postJson(path: string, token: string, body: unknown, signal?: AbortSignal): Promise<unknown> {
+  let response: Response;
+  try {
+    response = await fetch(resolveApiUrl(path), {
+      method: 'POST',
+      headers: buildCreateHeaders(token),
+      body: JSON.stringify(body),
+      signal,
+    });
+  } catch (error) {
+    if (isAbortError(error)) throw error;
+    throw new StudioRequestError(COPY.unableToReachServer);
+  }
+
+  const payload = await readPayload(response);
+  if (!response.ok || !isPlainRecord(payload) || payload.success !== true) {
+    throw new StudioRequestError(errorMessage(payload) ?? COPY.unableToCompleteCreation);
+  }
+
+  return payload.data;
+}
+
+async function readPayload(response: Response): Promise<unknown> {
+  const text = await response.text();
+  if (!text.trim()) return;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return;
+  }
+}
+
+function errorMessage(payload: unknown): string | undefined {
+  if (!isPlainRecord(payload) || !isPlainRecord(payload.error)) return;
+  const message = payload.error.message;
+  return typeof message === 'string' && message.trim() ? message : undefined;
+}
+
+function parseValidation(data: unknown): StudioValidationOutcome {
+  if (!isPlainRecord(data) || !isPlainRecord(data.report) || typeof data.report.success !== 'boolean') {
+    throw new StudioRequestError(COPY.unableToCompleteCreation);
+  }
+
+  return {
+    valid: data.report.success,
+    issues: parseIssues(data.report.issues),
+    draft: parseSelectorsField(data.selectors),
+    yaml: parseYamlField(data.yaml),
+  };
+}
+
+function parseSelectorsField(value: unknown): StudioDraft | undefined {
+  if (isAbsent(value)) return;
+  const draft = draftFromSelectors(value);
+  if (!draft) throw new StudioRequestError(COPY.unableToCompleteCreation);
+  return draft;
+}
+
+function parseYamlField(value: unknown): string | undefined {
+  if (isAbsent(value)) return;
+  if (typeof value !== 'string') throw new StudioRequestError(COPY.unableToCompleteCreation);
+  return value;
+}
+
+function parseIssues(value: unknown): readonly StudioIssue[] {
+  if (!Array.isArray(value)) throw new StudioRequestError(COPY.unableToCompleteCreation);
+  return value.map((item) => parseIssue(item));
+}
+
+function parseIssue(value: unknown): StudioIssue {
+  if (!isPlainRecord(value) || !Array.isArray(value.path) || typeof value.message !== 'string') {
+    throw new StudioRequestError(COPY.unableToCompleteCreation);
+  }
+
+  const code = knownIssueCode(value.code);
+  if (!code) throw new StudioRequestError(COPY.unableToCompleteCreation);
+
+  const path: string[] = [];
+  for (const segment of value.path) {
+    if (typeof segment !== 'string') throw new StudioRequestError(COPY.unableToCompleteCreation);
+    path.push(segment);
+  }
+
+  return { path, code, message: value.message };
+}
+
+function knownIssueCode(value: unknown): StudioIssueCode | undefined {
+  if (typeof value !== 'string') return;
+  for (const code of STUDIO_ISSUE_CODES) {
+    if (code === value) return code;
+  }
+  return;
+}
+
+function parsePreview(data: unknown): StudioPreview {
+  if (!isPlainRecord(data) || typeof data.item_count !== 'number' || !Array.isArray(data.sample_items)) {
+    throw new StudioRequestError(COPY.unableToCompleteCreation);
+  }
+
+  const titles: string[] = [];
+  for (const item of data.sample_items) {
+    if (!isPlainRecord(item) || typeof item.title !== 'string') {
+      throw new StudioRequestError(COPY.unableToCompleteCreation);
+    }
+    titles.push(item.title);
+  }
+
+  return {
+    itemCount: data.item_count,
+    titles,
+    warnings: parseWarnings(data.quality_report),
+    failureKind: parseFailureKind(data.failure_kind),
+  };
+}
+
+function parseWarnings(value: unknown): readonly string[] {
+  if (isAbsent(value)) return [];
+  if (!isPlainRecord(value) || !Array.isArray(value.warnings)) {
+    throw new StudioRequestError(COPY.unableToCompleteCreation);
+  }
+
+  const warnings: string[] = [];
+  for (const warning of value.warnings) {
+    if (typeof warning !== 'string') throw new StudioRequestError(COPY.unableToCompleteCreation);
+    warnings.push(warning);
+  }
+  return warnings;
+}
+
+function parseFailureKind(value: unknown): string | undefined {
+  if (isAbsent(value)) return;
+  if (typeof value !== 'string') throw new StudioRequestError(COPY.unableToCompleteCreation);
+  return value.length > 0 ? value : undefined;
+}
+
+function parseSuggestion(data: unknown): StudioSuggestion {
+  if (!isPlainRecord(data)) throw new StudioRequestError(COPY.unableToCompleteCreation);
+
+  const draft = isAbsent(data.selectors) ? undefined : draftFromSelectors(data.selectors);
+  if (data.selectors !== undefined && !isAbsent(data.selectors) && !draft) {
+    throw new StudioRequestError(COPY.unableToCompleteCreation);
+  }
+
+  const enhance = typeof data.enhance === 'boolean' ? data.enhance : (draft?.enhance ?? false);
+  const segmentStrategy = typeof data.segment_strategy === 'string' ? data.segment_strategy : '';
+  const chromeDrops =
+    isPlainRecord(data.admission_drops) && typeof data.admission_drops.chrome === 'number'
+      ? data.admission_drops.chrome
+      : 0;
+
+  return {
+    itemsSelector: draft?.itemsSelector ?? '',
+    enhance,
+    segmentStrategy,
+    chromeDrops,
+  };
+}
+
+function isAbsent(value: unknown): boolean {
+  return value === undefined || value === null;
+}
diff --git a/frontend/src/studio/useStudio.ts b/frontend/src/studio/useStudio.ts
new file mode 100644
index 00000000..c91c1d4d
--- /dev/null
+++ b/frontend/src/studio/useStudio.ts
@@ -0,0 +1,283 @@
+import { useEffect, useRef, useState } from 'preact/hooks';
+import { isAbortError } from '../feeds/feedsService';
+import { COPY } from '../journey/copy';
+import {
+  previewStudioFeed,
+  StudioRequestError,
+  suggestStudioSelectors,
+  validateStudioSelectors,
+  validateStudioYaml,
+  type StudioIssue,
+  type StudioPreview,
+  type StudioSuggestion,
+  type StudioValidationOutcome,
+} from './studioService';
+import {
+  addAttribute,
+  addPostProcessor,
+  applyItemsSuggestion,
+  emptyDraft,
+  removeAttribute,
+  removePostProcessor,
+  renamePostProcessor,
+  reuseDraftIds,
+  selectorsFromDraft,
+  updateAttribute,
+  updatePostProcessorField,
+  withEnhance,
+  withItemsSelector,
+  type AttributePatch,
+  type PostProcessorField,
+  type PostProcessorName,
+  type StudioDraft,
+} from './selectorDraft';
+
+export const STUDIO_VALIDATE_DELAY_MS = 300;
+
+interface StudioDocument {
+  readonly draft: StudioDraft;
+  readonly yaml: string;
+}
+
+export type StudioState =
+  | (StudioDocument & { readonly phase: 'editing'; readonly validated: boolean })
+  | (StudioDocument & { readonly phase: 'validating' })
+  | (StudioDocument & { readonly phase: 'invalid'; readonly issues: readonly StudioIssue[] })
+  | (StudioDocument & { readonly phase: 'previewing' })
+  | (StudioDocument & { readonly phase: 'previewed'; readonly preview: StudioPreview })
+  | (StudioDocument & { readonly phase: 'failed'; readonly message: string });
+
+type EditSource = 'selectors' | 'yaml';
+
+interface UseStudioOptions {
+  readonly url: string;
+  readonly token: string;
+  readonly validateDelayMs?: number;
+}
+
+export function useStudio({ url, token, validateDelayMs = STUDIO_VALIDATE_DELAY_MS }: UseStudioOptions) {
+  const [state, setState] = useState<StudioState>({
+    phase: 'editing',
+    draft: emptyDraft(),
+    yaml: '',
+    validated: false,
+  });
+  const [suggestion, setSuggestion] = useState<StudioSuggestion | undefined>(undefined);
+  const [documentRevision, setDocumentRevision] = useState(0);
+
+  const stateReference = useRef(state);
+  stateReference.current = state;
+  const editSourceReference = useRef<EditSource>('selectors');
+  const requestIdReference = useRef(0);
+  const previewRequestReference = useRef(0);
+  const suggestRequestReference = useRef(0);
+
+  useEffect(() => {
+    const requestId = ++requestIdReference.current;
+    const controller = new AbortController();
+    const timer = setTimeout(() => {
+      void runValidate(requestId, controller.signal);
+    }, validateDelayMs);
+
+    return () => {
+      clearTimeout(timer);
+      controller.abort();
+    };
+  }, [documentRevision, token, validateDelayMs]);
+
+  async function runValidate(requestId: number, signal: AbortSignal) {
+    const source = editSourceReference.current;
+    const sentDraft = stateReference.current.draft;
+    const sentYaml = stateReference.current.yaml;
+    setState((previous) => ({ phase: 'validating', draft: previous.draft, yaml: previous.yaml }));
+
+    try {
+      const outcome =
+        source === 'yaml'
+          ? await validateStudioYaml(token, sentYaml, signal)
+          : await validateStudioSelectors(token, sentDraft, signal);
+      if (signal.aborted || requestIdReference.current !== requestId) return;
+      commitValidation(outcome, source, sentDraft, sentYaml);
+    } catch (error) {
+      if (isAbortError(error) || signal.aborted || requestIdReference.current !== requestId) return;
+      setState((previous) => ({
+        phase: 'failed',
+        draft: previous.draft,
+        yaml: previous.yaml,
+        message: error instanceof StudioRequestError ? error.message : COPY.unableToReachServer,
+      }));
+    }
+  }
+
+  function commitValidation(
+    outcome: StudioValidationOutcome,
+    source: EditSource,
+    sentDraft: StudioDraft,
+    sentYaml: string
+  ) {
+    const syntaxError = outcome.issues.some((issue) => issue.code === 'parse');
+    let draft = sentDraft;
+    let yaml = sentYaml;
+
+    if (source === 'yaml') {
+      if (!syntaxError && outcome.draft) draft = reuseDraftIds(sentDraft, outcome.draft, false);
+      if (!syntaxError && outcome.yaml !== undefined) yaml = outcome.yaml;
+    } else if (outcome.draft) {
+      draft = reuseDraftIds(sentDraft, outcome.draft, true);
+      if (outcome.yaml !== undefined) yaml = outcome.yaml;
+    } else if (outcome.yaml !== undefined) {
+      yaml = outcome.yaml;
+    }
+
+    if (syntaxError || !outcome.valid) {
+      setState({ phase: 'invalid', draft, yaml, issues: outcome.issues });
+      return;
+    }
+
+    setState({ phase: 'editing', draft, yaml, validated: true });
+  }
+
+  function editSelectors(update: (draft: StudioDraft) => StudioDraft) {
+    editSourceReference.current = 'selectors';
+    previewRequestReference.current += 1;
+    setState((previous) => ({
+      phase: 'editing',
+      draft: update(previous.draft),
+      yaml: previous.yaml,
+      validated: false,
+    }));
+    setDocumentRevision((revision) => revision + 1);
+  }
+
+  const setItemsSelector = (itemsSelector: string) => {
+    editSelectors((draft) => withItemsSelector(draft, itemsSelector));
+  };
+
+  const setEnhance = (isEnhanced: boolean) => {
+    editSelectors((draft) => withEnhance(draft, isEnhanced));
+  };
+
+  const appendAttribute = () => {
+    editSelectors((draft) => addAttribute(draft));
+  };
+
+  const changeAttribute = (attributeId: string, patch: AttributePatch) => {
+    editSelectors((draft) => updateAttribute(draft, attributeId, patch));
+  };
+
+  const deleteAttribute = (attributeId: string) => {
+    editSelectors((draft) => removeAttribute(draft, attributeId));
+  };
+
+  const appendPostProcessor = (attributeId: string) => {
+    editSelectors((draft) => addPostProcessor(draft, attributeId));
+  };
+
+  const deletePostProcessor = (attributeId: string, processorId: string) => {
+    editSelectors((draft) => removePostProcessor(draft, attributeId, processorId));
+  };
+
+  const changePostProcessorName = (attributeId: string, processorId: string, name: PostProcessorName) => {
+    editSelectors((draft) => renamePostProcessor(draft, attributeId, processorId, name));
+  };
+
+  const changePostProcessorField = (
+    attributeId: string,
+    processorId: string,
+    field: PostProcessorField,
+    value: string
+  ) => {
+    editSelectors((draft) => updatePostProcessorField(draft, attributeId, processorId, field, value));
+  };
+
+  const setYaml = (yaml: string) => {
+    editSourceReference.current = 'yaml';
+    previewRequestReference.current += 1;
+    setState((previous) => ({
+      phase: 'editing',
+      draft: previous.draft,
+      yaml,
+      validated: false,
+    }));
+    setDocumentRevision((revision) => revision + 1);
+  };
+
+  async function requestPreview() {
+    const requestId = ++previewRequestReference.current;
+    const controller = new AbortController();
+    setState((previous) => ({ phase: 'previewing', draft: previous.draft, yaml: previous.yaml }));
+
+    try {
+      const preview = await previewStudioFeed(token, url, stateReference.current.draft, controller.signal);
+      if (previewRequestReference.current !== requestId) return;
+      setState((previous) => ({
+        phase: 'previewed',
+        draft: previous.draft,
+        yaml: previous.yaml,
+        preview,
+      }));
+    } catch (error) {
+      if (isAbortError(error) || previewRequestReference.current !== requestId) return;
+      setState((previous) => ({
+        phase: 'failed',
+        draft: previous.draft,
+        yaml: previous.yaml,
+        message: error instanceof StudioRequestError ? error.message : COPY.unableToReachServer,
+      }));
+    }
+  }
+
+  async function requestSuggestion() {
+    const requestId = ++suggestRequestReference.current;
+    try {
+      const nextSuggestion = await suggestStudioSelectors(
+        token,
+        url,
+        stateReference.current.draft.itemsSelector
+      );
+      if (suggestRequestReference.current !== requestId) return;
+      setSuggestion(nextSuggestion);
+      editSelectors((draft) =>
+        applyItemsSuggestion(draft, nextSuggestion.itemsSelector, nextSuggestion.enhance)
+      );
+    } catch (error) {
+      if (isAbortError(error) || suggestRequestReference.current !== requestId) return;
+      setState((previous) => ({
+        phase: 'failed',
+        draft: previous.draft,
+        yaml: previous.yaml,
+        message: error instanceof StudioRequestError ? error.message : COPY.unableToReachServer,
+      }));
+    }
+  }
+
+  return {
+    state,
+    suggestion,
+    setItemsSelector,
+    setEnhance,
+    appendAttribute,
+    changeAttribute,
+    deleteAttribute,
+    appendPostProcessor,
+    deletePostProcessor,
+    changePostProcessorName,
+    changePostProcessorField,
+    setYaml,
+    requestPreview: () => {
+      void requestPreview();
+    },
+    requestSuggestion: () => {
+      void requestSuggestion();
+    },
+    selectorsDocument: () => selectorsFromDraft(stateReference.current.draft),
+  };
+}
+
+export function studioIssues(state: StudioState): readonly StudioIssue[] {
+  return state.phase === 'invalid' ? state.issues : [];
+}
+
+export function hasSyntaxError(state: StudioState): boolean {
+  return state.phase === 'invalid' && state.issues.some((issue) => issue.code === 'parse');
+}

From 54293f0602718f08c9381a4a2fa17d32f5a65f32 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sat, 19 Sep 2026 23:09:48 +0200
Subject: [PATCH 013/108] feat(frontend): add visual selector builder to config
 studio

Fill the refine card with the items selector, enhance toggle, one-click capture suggestion, attribute extractors, and post-processors so refinement stays on shared primitives instead of a DOM picker.
---
 frontend/src/__tests__/ConfigStudio.test.tsx | 119 +++++
 frontend/src/__tests__/useSession.test.ts    |   5 +-
 frontend/src/components/App.tsx              |   3 +-
 frontend/src/components/ConfigStudio.tsx     | 432 ++++++++++++++++++-
 frontend/src/feed/useFeedFlow.ts             |   4 +-
 frontend/src/journey/copy.ts                 |  22 +
 6 files changed, 576 insertions(+), 9 deletions(-)
 create mode 100644 frontend/src/__tests__/ConfigStudio.test.tsx

diff --git a/frontend/src/__tests__/ConfigStudio.test.tsx b/frontend/src/__tests__/ConfigStudio.test.tsx
new file mode 100644
index 00000000..41b0d7c4
--- /dev/null
+++ b/frontend/src/__tests__/ConfigStudio.test.tsx
@@ -0,0 +1,119 @@
+import { describe, it, expect } from 'vitest';
+import { render, screen, fireEvent, waitFor } from '@testing-library/preact';
+import { http, HttpResponse } from 'msw';
+import { server } from './mocks/server';
+import { ConfigStudio } from '../components/ConfigStudio';
+import { COPY } from '../journey/copy';
+
+const pageUrl = 'https://example.com/articles';
+
+function echoValidate() {
+  server.use(
+    http.post('/api/v1/feeds/validate', async ({ request }) => {
+      const body: unknown = await request.json();
+      const selectors =
+        typeof body === 'object' && body && 'selectors' in body
+          ? body.selectors
+          : { items: { selector: 'article', enhance: false } };
+
+      return HttpResponse.json({
+        success: true,
+        data: {
+          report: { success: true, issues: [] },
+          selectors,
+          yaml: 'selectors: {}',
+        },
+      });
+    })
+  );
+}
+
+describe('ConfigStudio', () => {
+  it('hydrates the items selector from validate and focuses it', async () => {
+    render(<ConfigStudio url={pageUrl} token="tok" />);
+
+    const items = screen.getByLabelText(COPY.itemsSelector);
+    expect(screen.getByRole('button', { name: COPY.previewExtraction })).toBeDisabled();
+    await waitFor(() => expect(items).toHaveFocus());
+    await waitFor(() => expect(items).toHaveValue('article'));
+    expect(screen.getByLabelText(COPY.enhanceItems)).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: COPY.applySuggestion })).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: COPY.addAttribute })).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: COPY.previewExtraction })).toBeEnabled();
+  });
+
+  it('adds an attribute, chooses an extractor, and adds then removes a post-processor', async () => {
+    echoValidate();
+    render(<ConfigStudio url={pageUrl} token="tok" />);
+
+    fireEvent.click(screen.getByRole('button', { name: COPY.addAttribute }));
+    fireEvent.input(screen.getByLabelText(COPY.attributeName), { target: { value: 'title' } });
+    fireEvent.input(screen.getByLabelText(COPY.attributeSelector), { target: { value: 'h2' } });
+    fireEvent.change(screen.getByLabelText(COPY.extractor), { target: { value: 'attribute' } });
+
+    expect(screen.getByLabelText(COPY.htmlAttribute)).toBeInTheDocument();
+
+    fireEvent.click(screen.getByRole('button', { name: COPY.addPostProcessor }));
+    expect(screen.queryByLabelText(COPY.pattern)).not.toBeInTheDocument();
+    fireEvent.change(screen.getByLabelText(COPY.postProcessors), { target: { value: 'gsub' } });
+    expect(screen.getByLabelText(COPY.pattern)).toBeInTheDocument();
+    expect(screen.getByLabelText(COPY.replacement)).toBeInTheDocument();
+
+    fireEvent.click(screen.getByRole('button', { name: COPY.removeNamed('gsub') }));
+    expect(screen.queryByLabelText(COPY.pattern)).not.toBeInTheDocument();
+
+    fireEvent.click(screen.getByRole('button', { name: COPY.removeNamed('title') }));
+    expect(screen.queryByLabelText(COPY.attributeName)).not.toBeInTheDocument();
+  });
+
+  it('applies the capture suggestion in one click', async () => {
+    echoValidate();
+    server.use(
+      http.post('/api/v1/feeds/suggest_selectors', () =>
+        HttpResponse.json({
+          success: true,
+          data: {
+            selectors: { items: { selector: '.post', enhance: true } },
+            segment_strategy: 'list',
+            admission_drops: { chrome: 2 },
+            enhance: true,
+          },
+        })
+      )
+    );
+
+    render(<ConfigStudio url={pageUrl} token="tok" />);
+    fireEvent.click(screen.getByRole('button', { name: COPY.applySuggestion }));
+
+    await waitFor(() => expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('.post'));
+    expect(screen.getByLabelText(COPY.enhanceItems)).toBeChecked();
+    expect(screen.getByText(COPY.chromeDropped(2))).toBeInTheDocument();
+    expect(screen.getByText(/list/)).toBeInTheDocument();
+  });
+
+  it('previews sample titles after a successful check', async () => {
+    echoValidate();
+    server.use(
+      http.post('/api/v1/feeds/preview', () =>
+        HttpResponse.json({
+          success: true,
+          data: {
+            item_count: 1,
+            sample_items: [{ title: 'Sample headline' }],
+            quality_report: { warnings: [], metrics: { short_title_count: 0 } },
+            failure_kind: '',
+            validation_issues: [],
+          },
+        })
+      )
+    );
+
+    render(<ConfigStudio url={pageUrl} token="tok" />);
+    const preview = screen.getByRole('button', { name: COPY.previewExtraction });
+    await waitFor(() => expect(preview).toBeEnabled());
+    fireEvent.click(preview);
+
+    await waitFor(() => expect(screen.getByText('Sample headline')).toBeInTheDocument());
+    expect(screen.getByText(COPY.previewItemCount(1))).toBeInTheDocument();
+  });
+});
diff --git a/frontend/src/__tests__/useSession.test.ts b/frontend/src/__tests__/useSession.test.ts
index 74ff83de..f900f96f 100644
--- a/frontend/src/__tests__/useSession.test.ts
+++ b/frontend/src/__tests__/useSession.test.ts
@@ -84,10 +84,11 @@ describe('useSession', () => {
     );
 
     const { result } = renderHook(() => useSession());
-    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    await waitFor(() => {
+      expect(result.current.featuredFeeds.map((entry) => entry.id)).toEqual(['fao.org/newsroom']);
+    });
 
     expect(result.current.feedCreationEnabled).toBe(true);
-    expect(result.current.featuredFeeds.map((entry) => entry.id)).toEqual(['fao.org/newsroom']);
   });
 
   it('saves new tokens to persistent storage and does not write sessionStorage', async () => {
diff --git a/frontend/src/components/App.tsx b/frontend/src/components/App.tsx
index 56b29e22..3a40302f 100644
--- a/frontend/src/components/App.tsx
+++ b/frontend/src/components/App.tsx
@@ -65,6 +65,7 @@ export function App() {
     onCreateAnother,
     onRefine,
     onRetryPreview,
+    sourceUrl,
     setBookmarkletNotice,
     setTokenDraft,
     setTokenError,
@@ -112,7 +113,7 @@ export function App() {
       />
     );
   } else if (viewModel.kind === 'refine') {
-    bodyContent = <ConfigStudio />;
+    bodyContent = <ConfigStudio url={sourceUrl} token={token ?? ''} />;
   } else {
     bodyContent = (
       <CreateFeedPanel
diff --git a/frontend/src/components/ConfigStudio.tsx b/frontend/src/components/ConfigStudio.tsx
index 42e95bec..26359000 100644
--- a/frontend/src/components/ConfigStudio.tsx
+++ b/frontend/src/components/ConfigStudio.tsx
@@ -1,16 +1,438 @@
+import type { JSX } from 'preact';
+import { useEffect, useRef } from 'preact/hooks';
 import { COPY } from '../journey/copy';
+import { PreviewItem } from './PreviewItem';
+import {
+  EXTRACTOR_NAMES,
+  POST_PROCESSOR_NAMES,
+  type AttributeDraft,
+  type AttributePatch,
+  type ExtractorName,
+  type PostProcessorDraft,
+  type PostProcessorField,
+  type PostProcessorName,
+} from '../studio/selectorDraft';
+import { hasSyntaxError, useStudio, type StudioState } from '../studio/useStudio';
+
+interface ConfigStudioProperties {
+  readonly url: string;
+  readonly token: string;
+}
+
+export function ConfigStudio({ url, token }: ConfigStudioProperties) {
+  const studio = useStudio({ url, token });
+  const { state, suggestion } = studio;
+  const canPreview = (state.phase === 'editing' && state.validated) || state.phase === 'previewed';
+  const isBusy = state.phase === 'validating' || state.phase === 'previewing';
+  const itemsReference = useRef<HTMLInputElement>(null);
+
+  useEffect(() => {
+    itemsReference.current?.focus();
+  }, []);
 
-/** Empty refine shell. Selector controls land in a later phase. */
-export function ConfigStudio() {
   return (
     <section
       class="ui-card ui-card--padded ui-card--framed"
       data-state="refine"
       aria-labelledby="refine-title"
+      aria-busy={isBusy}
     >
-      <h1 id="refine-title" class="ui-display-title">
-        {COPY.refineSelectors}
-      </h1>
+      <div class="layout-stack">
+        <h1 id="refine-title" class="ui-display-title">
+          {COPY.refineSelectors}
+        </h1>
+
+        <label class="field-block" htmlFor="studio-items-selector">
+          <span class="ui-eyebrow">{COPY.itemsSelector}</span>
+          <input
+            id="studio-items-selector"
+            class="input input--mono"
+            value={state.draft.itemsSelector}
+            autoFocus
+            ref={itemsReference}
+            spellcheck={false}
+            onInput={(event) => studio.setItemsSelector(inputValue(event))}
+          />
+        </label>
+
+        <label class="field-block" htmlFor="studio-enhance">
+          <span class="ui-eyebrow">{COPY.enhanceItems}</span>
+          <input
+            id="studio-enhance"
+            type="checkbox"
+            checked={state.draft.enhance}
+            onChange={(event) => studio.setEnhance(isInputChecked(event))}
+          />
+        </label>
+
+        <div class="ui-actions">
+          <button type="button" class="btn btn--quiet" onClick={() => studio.requestSuggestion()}>
+            {COPY.applySuggestion}
+          </button>
+          <button type="button" class="btn" disabled={!canPreview} onClick={() => studio.requestPreview()}>
+            {state.phase === 'previewing' ? COPY.previewChecking : COPY.previewExtraction}
+          </button>
+        </div>
+
+        {suggestion ? (
+          <p>
+            <span class="ui-eyebrow">{COPY.suggestion}</span> <span>{suggestion.segmentStrategy}</span>{' '}
+            <span>{COPY.chromeDropped(suggestion.chromeDrops)}</span>
+          </p>
+        ) : undefined}
+
+        <div class="layout-stack">
+          <p class="ui-eyebrow">{COPY.attributeSelectors}</p>
+          {state.draft.attributes.map((attribute) => (
+            <AttributeEditor
+              key={attribute.id}
+              attribute={attribute}
+              isFrozen={hasSyntaxError(state)}
+              onChange={(patch) => studio.changeAttribute(attribute.id, patch)}
+              onRemove={() => studio.deleteAttribute(attribute.id)}
+              onAddProcessor={() => studio.appendPostProcessor(attribute.id)}
+              onRemoveProcessor={(processorId) => studio.deletePostProcessor(attribute.id, processorId)}
+              onRenameProcessor={(processorId, name) =>
+                studio.changePostProcessorName(attribute.id, processorId, name)
+              }
+              onProcessorField={(processorId, field, value) =>
+                studio.changePostProcessorField(attribute.id, processorId, field, value)
+              }
+            />
+          ))}
+          <button type="button" class="btn btn--quiet" onClick={() => studio.appendAttribute()}>
+            {COPY.addAttribute}
+          </button>
+        </div>
+
+        <PreviewReadout state={state} />
+
+        {state.phase === 'failed' ? <p role="alert">{state.message}</p> : undefined}
+      </div>
     </section>
   );
 }
+
+interface AttributeEditorProperties {
+  readonly attribute: AttributeDraft;
+  readonly isFrozen: boolean;
+  readonly onChange: (patch: AttributePatch) => void;
+  readonly onRemove: () => void;
+  readonly onAddProcessor: () => void;
+  readonly onRemoveProcessor: (processorId: string) => void;
+  readonly onRenameProcessor: (processorId: string, name: PostProcessorName) => void;
+  readonly onProcessorField: (processorId: string, field: PostProcessorField, value: string) => void;
+}
+
+function AttributeEditor({
+  attribute,
+  isFrozen,
+  onChange,
+  onRemove,
+  onAddProcessor,
+  onRemoveProcessor,
+  onRenameProcessor,
+  onProcessorField,
+}: AttributeEditorProperties) {
+  const nameId = `studio-attribute-name-${attribute.id}`;
+  const selectorId = `studio-attribute-selector-${attribute.id}`;
+  const extractorId = `studio-extractor-${attribute.id}`;
+
+  return (
+    <div class="layout-stack layout-section-divided">
+      <label class="field-block" htmlFor={nameId}>
+        <span class="ui-eyebrow">{COPY.attributeName}</span>
+        <input
+          id={nameId}
+          class="input"
+          value={attribute.name}
+          disabled={isFrozen}
+          onInput={(event) => onChange({ name: inputValue(event) })}
+        />
+      </label>
+      <label class="field-block" htmlFor={selectorId}>
+        <span class="ui-eyebrow">{COPY.attributeSelector}</span>
+        <input
+          id={selectorId}
+          class="input input--mono"
+          value={attribute.selector}
+          disabled={isFrozen}
+          spellcheck={false}
+          onInput={(event) => onChange({ selector: inputValue(event) })}
+        />
+      </label>
+      <label class="field-block" htmlFor={extractorId}>
+        <span class="ui-eyebrow">{COPY.extractor}</span>
+        <select
+          id={extractorId}
+          class="input"
+          value={attribute.extractor}
+          disabled={isFrozen}
+          onChange={(event) => {
+            const value = inputValue(event);
+            if (!isExtractorName(value)) return;
+            onChange({ extractor: value });
+          }}
+        >
+          {EXTRACTOR_NAMES.map((name) => (
+            <option key={name} value={name}>
+              {name}
+            </option>
+          ))}
+        </select>
+      </label>
+      {attribute.extractor === 'attribute' ? (
+        <label class="field-block" htmlFor={`studio-html-attribute-${attribute.id}`}>
+          <span class="ui-eyebrow">{COPY.htmlAttribute}</span>
+          <input
+            id={`studio-html-attribute-${attribute.id}`}
+            class="input input--mono"
+            value={attribute.attributeName}
+            disabled={isFrozen}
+            spellcheck={false}
+            onInput={(event) => onChange({ attributeName: inputValue(event) })}
+          />
+        </label>
+      ) : undefined}
+      {attribute.extractor === 'static' ? (
+        <label class="field-block" htmlFor={`studio-static-${attribute.id}`}>
+          <span class="ui-eyebrow">{COPY.staticValue}</span>
+          <input
+            id={`studio-static-${attribute.id}`}
+            class="input"
+            value={attribute.staticValue}
+            disabled={isFrozen}
+            onInput={(event) => onChange({ staticValue: inputValue(event) })}
+          />
+        </label>
+      ) : undefined}
+
+      <div class="layout-stack layout-stack--tight">
+        <p class="ui-eyebrow">{COPY.postProcessors}</p>
+        {attribute.postProcessors.map((processor) => (
+          <ProcessorEditor
+            key={processor.id}
+            processor={processor}
+            isFrozen={isFrozen}
+            onRename={(name) => onRenameProcessor(processor.id, name)}
+            onField={(field, value) => onProcessorField(processor.id, field, value)}
+            onRemove={() => onRemoveProcessor(processor.id)}
+          />
+        ))}
+        <button type="button" class="btn btn--quiet" disabled={isFrozen} onClick={onAddProcessor}>
+          {COPY.addPostProcessor}
+        </button>
+      </div>
+
+      <button
+        type="button"
+        class="btn btn--quiet btn--linkish"
+        disabled={isFrozen}
+        aria-label={COPY.removeNamed(attribute.name.trim() || COPY.attributeName)}
+        onClick={onRemove}
+      >
+        {COPY.removeAttribute}
+      </button>
+    </div>
+  );
+}
+
+interface ProcessorEditorProperties {
+  readonly processor: PostProcessorDraft;
+  readonly isFrozen: boolean;
+  readonly onRename: (name: PostProcessorName) => void;
+  readonly onField: (field: PostProcessorField, value: string) => void;
+  readonly onRemove: () => void;
+}
+
+function ProcessorEditor({ processor, isFrozen, onRename, onField, onRemove }: ProcessorEditorProperties) {
+  const selectId = `studio-processor-${processor.id}`;
+
+  return (
+    <div class="layout-stack layout-stack--tight">
+      {processor.name === 'unrecognized' ? (
+        <p class="input input--mono">{processorCaption(processor)}</p>
+      ) : (
+        <label class="field-block" htmlFor={selectId}>
+          <span class="ui-eyebrow">{COPY.postProcessors}</span>
+          <select
+            id={selectId}
+            class="input"
+            value={processor.name}
+            disabled={isFrozen}
+            onChange={(event) => {
+              const value = inputValue(event);
+              if (!isPostProcessorName(value)) return;
+              onRename(value);
+            }}
+          >
+            {POST_PROCESSOR_NAMES.map((name) => (
+              <option key={name} value={name}>
+                {name}
+              </option>
+            ))}
+          </select>
+        </label>
+      )}
+      <ProcessorFields processor={processor} isFrozen={isFrozen} onField={onField} />
+      <button
+        type="button"
+        class="btn btn--quiet btn--linkish"
+        disabled={isFrozen}
+        aria-label={COPY.removeNamed(processorCaption(processor))}
+        onClick={onRemove}
+      >
+        {COPY.removeAttribute}
+      </button>
+    </div>
+  );
+}
+
+function ProcessorFields({
+  processor,
+  isFrozen,
+  onField,
+}: {
+  readonly processor: PostProcessorDraft;
+  readonly isFrozen: boolean;
+  readonly onField: (field: PostProcessorField, value: string) => void;
+}) {
+  switch (processor.name) {
+    case 'gsub': {
+      return (
+        <>
+          <ProcessorInput
+            id={`studio-pattern-${processor.id}`}
+            label={COPY.pattern}
+            value={processor.pattern}
+            isFrozen={isFrozen}
+            onInput={(value) => onField('pattern', value)}
+          />
+          <ProcessorInput
+            id={`studio-replacement-${processor.id}`}
+            label={COPY.replacement}
+            value={processor.replacement}
+            isFrozen={isFrozen}
+            onInput={(value) => onField('replacement', value)}
+          />
+        </>
+      );
+    }
+    case 'substring': {
+      return (
+        <>
+          <ProcessorInput
+            id={`studio-start-${processor.id}`}
+            label={COPY.rangeStart}
+            value={processor.start}
+            isFrozen={isFrozen}
+            onInput={(value) => onField('start', value)}
+          />
+          <ProcessorInput
+            id={`studio-end-${processor.id}`}
+            label={COPY.rangeEnd}
+            value={processor.end}
+            isFrozen={isFrozen}
+            onInput={(value) => onField('end', value)}
+          />
+        </>
+      );
+    }
+    case 'template': {
+      return (
+        <ProcessorInput
+          id={`studio-template-${processor.id}`}
+          label={COPY.templateString}
+          value={processor.template}
+          isFrozen={isFrozen}
+          onInput={(value) => onField('template', value)}
+        />
+      );
+    }
+    default: {
+      return;
+    }
+  }
+}
+
+function ProcessorInput({
+  id,
+  label,
+  value,
+  isFrozen,
+  onInput,
+}: {
+  readonly id: string;
+  readonly label: string;
+  readonly value: string;
+  readonly isFrozen: boolean;
+  readonly onInput: (value: string) => void;
+}) {
+  return (
+    <label class="field-block" htmlFor={id}>
+      <span class="ui-eyebrow">{label}</span>
+      <input
+        id={id}
+        class="input input--mono"
+        value={value}
+        disabled={isFrozen}
+        spellcheck={false}
+        onInput={(event) => onInput(inputValue(event))}
+      />
+    </label>
+  );
+}
+
+function PreviewReadout({ state }: { readonly state: StudioState }) {
+  if (state.phase === 'previewing') {
+    return <p class="ui-eyebrow">{COPY.previewChecking}</p>;
+  }
+
+  if (state.phase !== 'previewed') return;
+
+  return (
+    <div class="layout-stack layout-stack--tight" aria-label={COPY.previewRegion}>
+      <p class="ui-eyebrow">{COPY.previewItemCount(state.preview.itemCount)}</p>
+      {state.preview.titles.length > 0 ? (
+        <ul class="ui-item-list" role="list">
+          {state.preview.titles.map((title, index) => (
+            <li key={`${title}-${index}`} class="ui-item">
+              <PreviewItem title={title} />
+            </li>
+          ))}
+        </ul>
+      ) : undefined}
+      {state.preview.warnings.map((warning) => (
+        <p key={warning}>{warning}</p>
+      ))}
+    </div>
+  );
+}
+
+function inputValue(event: JSX.TargetedEvent<HTMLInputElement | HTMLSelectElement>): string {
+  return event.currentTarget.value;
+}
+
+function isInputChecked(event: JSX.TargetedEvent<HTMLInputElement>): boolean {
+  return event.currentTarget.checked;
+}
+
+function isExtractorName(value: string): value is ExtractorName {
+  for (const name of EXTRACTOR_NAMES) {
+    if (name === value) return true;
+  }
+  return false;
+}
+
+function isPostProcessorName(value: string): value is PostProcessorName {
+  for (const name of POST_PROCESSOR_NAMES) {
+    if (name === value) return true;
+  }
+  return false;
+}
+
+function processorCaption(processor: PostProcessorDraft): string {
+  if (processor.name !== 'unrecognized') return processor.name;
+  const rawName = processor.raw.name;
+  return typeof rawName === 'string' ? rawName : processor.name;
+}
diff --git a/frontend/src/feed/useFeedFlow.ts b/frontend/src/feed/useFeedFlow.ts
index 54e13f8d..23cf8105 100644
--- a/frontend/src/feed/useFeedFlow.ts
+++ b/frontend/src/feed/useFeedFlow.ts
@@ -240,12 +240,13 @@ export function useFeedFlow({
     setFocusCreateComposerKey((current) => current + 1);
   }, [clearError, clearResult, createEntryKey, feedFieldErrors.form, route]);
 
+  const sourceUrl = inMemorySourceUrl(feedFormData.url, result?.feed.url);
   const viewModel = decideJourney({
     creationError,
     feedFieldErrors,
     isCreating,
     route,
-    sourceUrl: inMemorySourceUrl(feedFormData.url, result?.feed.url),
+    sourceUrl,
     tokenError,
     result,
   });
@@ -289,6 +290,7 @@ export function useFeedFlow({
       navigate({ kind: 'refine' });
     },
     onRetryPreview: retryPreviewFetch,
+    sourceUrl,
     setBookmarkletNotice,
     setTokenDraft,
     setTokenError,
diff --git a/frontend/src/journey/copy.ts b/frontend/src/journey/copy.ts
index 41bc3a5a..90b964f7 100644
--- a/frontend/src/journey/copy.ts
+++ b/frontend/src/journey/copy.ts
@@ -68,4 +68,26 @@ export const COPY = {
   footerNav: 'Footer navigation',
   previewStatus: 'Feed preview status',
   previewRegion: 'Feed preview',
+  itemsSelector: 'Items selector',
+  enhanceItems: 'Enhance items',
+  applySuggestion: 'Apply suggestion',
+  suggestion: 'Suggestion',
+  chromeDropped: (count: number) => `${count} chrome dropped`,
+  attributeSelectors: 'Attributes',
+  attributeName: 'Name',
+  attributeSelector: 'Selector',
+  extractor: 'Extractor',
+  htmlAttribute: 'HTML attribute',
+  staticValue: 'Static value',
+  addAttribute: 'Add attribute',
+  removeAttribute: 'Remove',
+  removeNamed: (name: string) => `Remove ${name}`,
+  postProcessors: 'Post-processors',
+  addPostProcessor: 'Add post-processor',
+  previewExtraction: 'Preview',
+  pattern: 'Pattern',
+  replacement: 'Replacement',
+  rangeStart: 'Start',
+  rangeEnd: 'End',
+  templateString: 'Template',
 } as const;

From b9bcc16af01c5a5c2a66988e6edeb295f0504d26 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sat, 19 Sep 2026 23:11:02 +0200
Subject: [PATCH 014/108] feat(frontend): add synchronized yaml panel with
 validation issues

Keep YAML as the same config as the builder by posting it through validate, and surface parse failures as a syntax notice so the builder does not hydrate from broken text.
---
 frontend/src/__tests__/YamlPanel.test.tsx | 52 +++++++++++++++++++++++
 frontend/src/components/ConfigStudio.tsx  | 10 ++++-
 frontend/src/components/YamlPanel.tsx     | 45 ++++++++++++++++++++
 frontend/src/journey/copy.ts              |  2 +
 frontend/src/styles/main.css              |  4 ++
 5 files changed, 112 insertions(+), 1 deletion(-)
 create mode 100644 frontend/src/__tests__/YamlPanel.test.tsx
 create mode 100644 frontend/src/components/YamlPanel.tsx

diff --git a/frontend/src/__tests__/YamlPanel.test.tsx b/frontend/src/__tests__/YamlPanel.test.tsx
new file mode 100644
index 00000000..3e3f1538
--- /dev/null
+++ b/frontend/src/__tests__/YamlPanel.test.tsx
@@ -0,0 +1,52 @@
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/preact';
+import { YamlPanel } from '../components/YamlPanel';
+import { COPY } from '../journey/copy';
+import type { StudioIssue } from '../studio/studioService';
+
+const constraintIssue: StudioIssue = {
+  path: ['selectors', 'items', 'selector'],
+  code: 'constraint',
+  message: 'is too short',
+};
+
+const parseIssue: StudioIssue = {
+  path: [],
+  code: 'parse',
+  message: 'found unexpected end',
+};
+
+describe('YamlPanel', () => {
+  it('lists validation issues as path, code, and message', () => {
+    render(
+      <YamlPanel
+        yaml="selectors: {}"
+        issues={[constraintIssue]}
+        hasSyntaxError={false}
+        onYamlInput={vi.fn()}
+      />
+    );
+
+    expect(screen.getByLabelText(COPY.yamlConfig)).toHaveValue('selectors: {}');
+    expect(screen.getByText('selectors.items.selector')).toBeInTheDocument();
+    expect(screen.getByText('constraint')).toBeInTheDocument();
+    expect(screen.getByText('is too short')).toBeInTheDocument();
+    expect(screen.queryByRole('status')).not.toBeInTheDocument();
+  });
+
+  it('shows a syntax notice when the yaml does not parse', () => {
+    render(<YamlPanel yaml="selectors: [" issues={[parseIssue]} hasSyntaxError onYamlInput={vi.fn()} />);
+
+    expect(screen.getByRole('status')).toHaveTextContent(COPY.yamlSyntax);
+    expect(screen.getByText('parse')).toBeInTheDocument();
+  });
+
+  it('forwards textarea edits', () => {
+    const onYamlInput = vi.fn<(yaml: string) => void>();
+    render(<YamlPanel yaml="" issues={[]} hasSyntaxError={false} onYamlInput={onYamlInput} />);
+
+    fireEvent.input(screen.getByLabelText(COPY.yamlConfig), { target: { value: 'selectors:\n' } });
+
+    expect(onYamlInput).toHaveBeenCalledWith('selectors:\n');
+  });
+});
diff --git a/frontend/src/components/ConfigStudio.tsx b/frontend/src/components/ConfigStudio.tsx
index 26359000..9cc7c006 100644
--- a/frontend/src/components/ConfigStudio.tsx
+++ b/frontend/src/components/ConfigStudio.tsx
@@ -2,6 +2,7 @@ import type { JSX } from 'preact';
 import { useEffect, useRef } from 'preact/hooks';
 import { COPY } from '../journey/copy';
 import { PreviewItem } from './PreviewItem';
+import { YamlPanel } from './YamlPanel';
 import {
   EXTRACTOR_NAMES,
   POST_PROCESSOR_NAMES,
@@ -12,7 +13,7 @@ import {
   type PostProcessorField,
   type PostProcessorName,
 } from '../studio/selectorDraft';
-import { hasSyntaxError, useStudio, type StudioState } from '../studio/useStudio';
+import { hasSyntaxError, studioIssues, useStudio, type StudioState } from '../studio/useStudio';
 
 interface ConfigStudioProperties {
   readonly url: string;
@@ -105,6 +106,13 @@ export function ConfigStudio({ url, token }: ConfigStudioProperties) {
           </button>
         </div>
 
+        <YamlPanel
+          yaml={state.yaml}
+          issues={studioIssues(state)}
+          hasSyntaxError={hasSyntaxError(state)}
+          onYamlInput={(yaml) => studio.setYaml(yaml)}
+        />
+
         <PreviewReadout state={state} />
 
         {state.phase === 'failed' ? <p role="alert">{state.message}</p> : undefined}
diff --git a/frontend/src/components/YamlPanel.tsx b/frontend/src/components/YamlPanel.tsx
new file mode 100644
index 00000000..4e0eadcf
--- /dev/null
+++ b/frontend/src/components/YamlPanel.tsx
@@ -0,0 +1,45 @@
+import type { JSX } from 'preact';
+import { COPY } from '../journey/copy';
+import type { StudioIssue } from '../studio/studioService';
+
+interface YamlPanelProperties {
+  readonly yaml: string;
+  readonly issues: readonly StudioIssue[];
+  readonly hasSyntaxError: boolean;
+  readonly onYamlInput: (yaml: string) => void;
+}
+
+export function YamlPanel({ yaml, issues, hasSyntaxError, onYamlInput }: YamlPanelProperties) {
+  return (
+    <div class="layout-stack">
+      <label class="field-block" htmlFor="studio-yaml">
+        <span class="ui-eyebrow">{COPY.yamlConfig}</span>
+        <textarea
+          id="studio-yaml"
+          class="input input--mono studio-yaml"
+          value={yaml}
+          spellcheck={false}
+          onInput={(event) => onYamlInput(textareaValue(event))}
+        />
+      </label>
+      {hasSyntaxError ? <p role="status">{COPY.yamlSyntax}</p> : undefined}
+      {issues.length > 0 ? (
+        <ul>
+          {issues.map((issue) => (
+            <li key={issueKey(issue)}>
+              <span>{issue.path.join('.')}</span> <span>{issue.code}</span> <span>{issue.message}</span>
+            </li>
+          ))}
+        </ul>
+      ) : undefined}
+    </div>
+  );
+}
+
+function textareaValue(event: JSX.TargetedEvent<HTMLTextAreaElement>): string {
+  return event.currentTarget.value;
+}
+
+function issueKey(issue: StudioIssue): string {
+  return `${issue.path.join('.')}:${issue.code}:${issue.message}`;
+}
diff --git a/frontend/src/journey/copy.ts b/frontend/src/journey/copy.ts
index 90b964f7..4e32b2b5 100644
--- a/frontend/src/journey/copy.ts
+++ b/frontend/src/journey/copy.ts
@@ -85,6 +85,8 @@ export const COPY = {
   postProcessors: 'Post-processors',
   addPostProcessor: 'Add post-processor',
   previewExtraction: 'Preview',
+  yamlConfig: 'YAML',
+  yamlSyntax: 'YAML could not be parsed.',
   pattern: 'Pattern',
   replacement: 'Replacement',
   rangeStart: 'Start',
diff --git a/frontend/src/styles/main.css b/frontend/src/styles/main.css
index 93935919..c104129a 100644
--- a/frontend/src/styles/main.css
+++ b/frontend/src/styles/main.css
@@ -572,6 +572,10 @@
   }
 }
 
+.studio-yaml {
+  min-height: calc(var(--space-7) * 4);
+}
+
 @keyframes spin {
   to {
     transform: rotate(360deg);

From 3683a6f593658fd044a4a445c69446f52e2349a6 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sat, 19 Sep 2026 23:18:26 +0200
Subject: [PATCH 015/108] feat(studio): generate refined feeds and document the
 refine surface

Save posts the validated selectors through the existing create path and returns to the result view, and the refine route is now part of the journey grammar and operator docs.
---
 AGENTS.md                                    |  17 +++
 CONTEXT.md                                   |   6 +
 docs/design-system.md                        |   7 +-
 frontend/e2e/smoke.spec.ts                   | 120 +++++++++++++++++++
 frontend/src/__tests__/App.contract.test.tsx |  75 ++++++++++++
 frontend/src/__tests__/ConfigStudio.test.tsx |  27 ++++-
 frontend/src/components/App.tsx              |   3 +-
 frontend/src/components/ConfigStudio.tsx     |  25 +++-
 frontend/src/feed/useFeedCreation.ts         |   4 +-
 frontend/src/feed/useFeedFlow.ts             |  31 +++++
 frontend/src/feeds/feedsService.ts           |  11 +-
 frontend/src/journey/copy.ts                 |   1 +
 frontend/src/studio/useStudio.ts             |  28 ++++-
 13 files changed, 339 insertions(+), 16 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 59818255..5fc5a093 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -74,3 +74,20 @@ Public feed-directory metadata for embedded and local configs.
 | Contract SSOT | Request specs under `spec/html2rss/web/api/v1_spec.rb` and generated `public/openapi.yaml` |
 
 After handler or envelope changes: `make openapi` and `make ci-ready`.
+
+## Config studio API
+
+Token-holder refinement of the selectors subtree, then generate via create.
+
+| Item | Detail |
+| --- | --- |
+| Endpoints | `POST /api/v1/feeds/validate`, `POST /api/v1/feeds/preview`, `POST /api/v1/feeds/suggest_selectors` |
+| Create | `POST /api/v1/feeds` accepts optional `selectors` (same access token as validate) |
+| Flag | `STUDIO_ENABLED` (development/test default `true`; otherwise `false`) |
+| Disabled response | `403` when the flag is off |
+| Auth | Access token required on validate, preview, suggest, and create |
+| Live fetch | Preview and suggest also need `AUTO_SOURCE_ENABLED` |
+| Frontend | `#/refine` is memory-bound; missing URL recovers to remounted `#/create` |
+| Contract SSOT | Request specs under `spec/html2rss/web/api/v1_spec.rb` and generated `public/openapi.yaml` |
+
+After handler or envelope changes: `make openapi` and `make ci-ready`.
diff --git a/CONTEXT.md b/CONTEXT.md
index 81c2ec43..7b8431a5 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -28,6 +28,12 @@ On create, `findCatalogEntries` matches the typed query against the catalog (URL
 ### CreateEntry remount
 Visiting create (including hashbang `#!/…` → `#/…`) bumps `createEntryKey` so the create surface remounts. Remount alone does not auto-submit; auto-submit requires `prefillUrl`.
 
+### Config Studio
+The `#/refine` surface for editing selectors before a feed is generated. Memory-bound to the in-memory page URL (no token in the route). The visual builder and YAML are one document; only `studioService` unwraps the studio envelope. Save posts refined selectors through Creation IO and returns to the result view.
+
+### Refined Selectors
+The allowlisted `selectors` document a token holder may attach on feed creation. Signed into the feed token and resolved on later serves. Not a full config: channel, headers, and strategy stay denied.
+
 ### Unmatched result
 A result route whose in-memory created feed token does not match the route `feedToken`. Feed Flow replaces to create without prefill (no second journey decide elsewhere).
 
diff --git a/docs/design-system.md b/docs/design-system.md
index ca3a8723..d34473a4 100644
--- a/docs/design-system.md
+++ b/docs/design-system.md
@@ -40,10 +40,12 @@ If a page looks like it came from a different product, the change is wrong even
 
 - **Create:** URL field is the task. Visiting `#/create` or `#!/create` remounts create; hashbang aliases canonicalize to `#/create`. Bare create does not auto-submit. When the typed query finds catalog entries (URL equivalence or text substring), show matching feeds as a subordinate list under the field — never a second primary task or in-app catalog browser. On an empty Create URL, up to three Feed Directory starters may appear as subordinate chrome (lean: `.ui-eyebrow` + list + demoted `utility-link` escape under the list when creation is enabled; Notice when creation is disabled). Escape and utility-strip share **Browse Feed Directory (N)** (`catalogEntries.length`); hide starters and the under-list escape while typing, when find has hits, or while creating.
 - **Token gate:** a native `<dialog>` over the still-mounted, inert URL task (one interactive task). Auth copy is in-field (`tokenError`); ActionFeedback stays on create. Access Token persists until Logout with no storage UI.
-- **Result:** primary CTA is **Copy feed URL**. Open feed / JSON / feed-reader are demoted secondary actions and stay available while preview loads. Preview is non-blocking confirmation only.
+- **Result:** primary CTA is **Copy feed URL**. Open feed / JSON / feed-reader are demoted secondary actions and stay available while preview loads. Preview is non-blocking confirmation only. **Refine selectors** is one quiet action beside create another.
+- **Empty extraction:** **Refine selectors** is one quiet action beside Try again when the extraction is empty. It is not offered for other create errors.
+- **Refine:** `#/refine` is memory-bound. No token in the route. A missing in-memory URL recovers onto remounted `#/create`. The items selector is the task. YAML is the same config, not a second document. Primary completion is **Save and generate feed**, which returns to the result view.
 - **Unmatched result:** `#/result/:token` is valid only with a matching in-memory result. Missing or mismatched tokens recover onto remounted `#/create` (no API rehydrate, no failure chrome, no durable shareable result page).
 - **Status eyebrow:** one vocabulary (`Feed ready`) on the result header; preview progress lives in the preview section.
-- **Focus:** create autofocuses the URL field; token autofocuses the token field; result focuses the Copy control.
+- **Focus:** create autofocuses the URL field; token autofocuses the token field; result focuses the Copy control; refine focuses the items selector.
 
 ### Vocabulary
 
@@ -53,6 +55,7 @@ If a page looks like it came from a different product, the change is wrong even
 | Output | **Feed URL** |
 | Create | **Create feed** / **Creating feed** |
 | Result | **Feed ready** / **Copy feed URL** |
+| Refine | **Refine selectors** / **Save and generate feed** |
 | Retry | **Try again** (button only) |
 | Preview | **Checking preview** / **Check again** |
 | Catalog | **Feed Directory** |
diff --git a/frontend/e2e/smoke.spec.ts b/frontend/e2e/smoke.spec.ts
index 51c31868..b02613b7 100644
--- a/frontend/e2e/smoke.spec.ts
+++ b/frontend/e2e/smoke.spec.ts
@@ -208,4 +208,124 @@ test.describe('frontend smoke', () => {
     await expect(page.getByText('Saved result unavailable')).toHaveCount(0);
     await expect(page.locator('.result-recovery')).toHaveCount(0);
   });
+
+  test('recovers an empty refine route onto remounted create', async ({ page }) => {
+    await page.route(/\/api\/v1$/, async (route) => {
+      await route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          success: true,
+          data: {
+            api: {
+              name: 'html2rss-web API',
+              description: 'RESTful API for converting websites to RSS feeds',
+              openapi_url: 'https://example.test/openapi.yaml',
+            },
+            instance: {
+              feed_creation: { enabled: true, access_token_required: true },
+              catalog: { enabled: false, url: '/api/v1/configs' },
+            },
+          },
+        }),
+      });
+    });
+
+    await page.goto('/#/refine');
+
+    await expect(page).toHaveURL(/\/#\/create$/);
+    await expect(page.getByLabel(COPY.urlLabel)).toBeVisible();
+    await expect(page.getByRole('heading', { name: COPY.refineSelectors })).toHaveCount(0);
+  });
+
+  test('refines a result and generates the feed without a live scrape', async ({ page }) => {
+    await page.route(/\/api\/v1$/, async (route) => {
+      await route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          success: true,
+          data: {
+            api: {
+              name: 'html2rss-web API',
+              description: 'RESTful API for converting websites to RSS feeds',
+              openapi_url: 'https://example.test/openapi.yaml',
+            },
+            instance: {
+              feed_creation: { enabled: true, access_token_required: true },
+              catalog: { enabled: false, url: '/api/v1/configs' },
+            },
+          },
+        }),
+      });
+    });
+
+    await page.route(/\/api\/v1\/feeds$/, async (route) => {
+      await route.fulfill({
+        status: 201,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          success: true,
+          data: {
+            feed: {
+              id: 'feed-123',
+              name: 'Example Feed',
+              url: 'https://example.com/articles',
+              feed_token: 'generated-token',
+              public_url: '/api/v1/feeds/generated-token',
+              json_public_url: '/api/v1/feeds/generated-token.json',
+              created_at: '2026-04-05T08:59:00.000Z',
+              updated_at: '2026-04-05T09:00:00.000Z',
+            },
+          },
+        }),
+      });
+    });
+
+    await page.route(/\/api\/v1\/feeds\/generated-token\.json$/, async (route) => {
+      await route.fulfill({
+        status: 200,
+        contentType: 'application/feed+json',
+        body: JSON.stringify({ items: [] }),
+      });
+    });
+
+    await page.route(/\/api\/v1\/feeds\/validate$/, async (route) => {
+      await route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          success: true,
+          data: {
+            report: { success: true, issues: [] },
+            selectors: { items: { selector: 'article', enhance: false } },
+            yaml: 'selectors:\n  items:\n    selector: article\n    enhance: false\n',
+          },
+        }),
+      });
+    });
+
+    await page.addInitScript(() => {
+      localStorage.setItem('html2rss_access_token', 'token-123');
+    });
+
+    await page.goto('/');
+    await page.getByLabel(COPY.urlLabel).fill('https://example.com/articles');
+    await page.getByRole('button', { name: COPY.createFeed }).click();
+    await expect(page.getByText(COPY.feedReady)).toBeVisible();
+
+    await page.getByRole('button', { name: COPY.refineSelectors }).click();
+    await expect(page).toHaveURL(/\/#\/refine$/);
+    const save = page.getByRole('button', { name: COPY.saveAndGenerate });
+    await expect(save).toBeEnabled();
+
+    const refined = page.waitForRequest((request) => {
+      if (request.method() !== 'POST' || !request.url().endsWith('/api/v1/feeds')) return false;
+      return request.postData()?.includes('"selectors"') ?? false;
+    });
+    await save.click();
+    await refined;
+    await expect(page.getByText(COPY.feedReady)).toBeVisible();
+    await expect(page).toHaveURL(/\/#\/result\/generated-token$/);
+  });
 });
diff --git a/frontend/src/__tests__/App.contract.test.tsx b/frontend/src/__tests__/App.contract.test.tsx
index e3ec55d4..4a6ff197 100644
--- a/frontend/src/__tests__/App.contract.test.tsx
+++ b/frontend/src/__tests__/App.contract.test.tsx
@@ -150,4 +150,79 @@ describe('App contract', () => {
     expect(localStorage.getItem('html2rss_access_token')).toBeNull();
     expect(sessionStorage.getItem('html2rss_access_token')).toBeNull();
   });
+
+  it('posts refined selectors from the studio and returns to the result view', async () => {
+    const nativeFetch = fetch;
+    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockImplementation((input, init) => {
+      if (String(input).endsWith('/api/v1/feeds/generated-token.json')) {
+        return Promise.resolve(
+          Response.json(
+            {
+              items: [
+                {
+                  title: 'Contract Item',
+                  content_text: 'Contract preview excerpt.',
+                  url: 'https://example.com/contract-item',
+                  date_published: '2024-01-01T00:00:00Z',
+                },
+              ],
+            },
+            { status: 200, headers: { 'Content-Type': 'application/feed+json' } }
+          )
+        );
+      }
+
+      return nativeFetch(input, init);
+    });
+
+    const bodies: unknown[] = [];
+    server.use(
+      http.post('/api/v1/feeds', async ({ request }) => {
+        const body: unknown = await request.json();
+        bodies.push(body);
+        const url = readUrl(body) ?? 'https://example.com/articles';
+
+        return HttpResponse.json(
+          buildFeedResponse({
+            url,
+            feed_token: 'generated-token',
+            public_url: '/api/v1/feeds/generated-token',
+            json_public_url: '/api/v1/feeds/generated-token.json',
+          }),
+          { status: 201 }
+        );
+      })
+    );
+
+    render(<App />);
+
+    await waitFor(() => {
+      expect(screen.getByLabelText(COPY.urlLabel)).toBeInTheDocument();
+    });
+
+    fireEvent.input(screen.getByLabelText(COPY.urlLabel), {
+      target: { value: 'https://example.com/articles' },
+    });
+    fireEvent.click(screen.getByRole('button', { name: COPY.createFeed }));
+
+    await screen.findByText(COPY.feedReady);
+    fireEvent.click(screen.getByRole('button', { name: COPY.refineSelectors }));
+
+    const save = await screen.findByRole('button', { name: COPY.saveAndGenerate });
+    await waitFor(() => expect(save).toBeEnabled());
+    fireEvent.click(save);
+
+    await screen.findByText(COPY.feedReady);
+    expect(bodies).toHaveLength(2);
+    expect(bodies[1]).toMatchObject({
+      url: 'https://example.com/articles',
+      selectors: { items: { selector: 'article', enhance: false } },
+    });
+    fetchSpy.mockRestore();
+  });
 });
+
+function readUrl(body: unknown): string | undefined {
+  if (!body || typeof body !== 'object' || !('url' in body)) return undefined;
+  return typeof body.url === 'string' ? body.url : undefined;
+}
diff --git a/frontend/src/__tests__/ConfigStudio.test.tsx b/frontend/src/__tests__/ConfigStudio.test.tsx
index 41b0d7c4..d3728920 100644
--- a/frontend/src/__tests__/ConfigStudio.test.tsx
+++ b/frontend/src/__tests__/ConfigStudio.test.tsx
@@ -1,4 +1,4 @@
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, vi } from 'vitest';
 import { render, screen, fireEvent, waitFor } from '@testing-library/preact';
 import { http, HttpResponse } from 'msw';
 import { server } from './mocks/server';
@@ -7,6 +7,11 @@ import { COPY } from '../journey/copy';
 
 const pageUrl = 'https://example.com/articles';
 
+function renderStudio(onGenerate = vi.fn<(selectors: Record<string, unknown>) => Promise<void>>()) {
+  render(<ConfigStudio url={pageUrl} token="tok" onGenerate={onGenerate} />);
+  return onGenerate;
+}
+
 function echoValidate() {
   server.use(
     http.post('/api/v1/feeds/validate', async ({ request }) => {
@@ -30,7 +35,7 @@ function echoValidate() {
 
 describe('ConfigStudio', () => {
   it('hydrates the items selector from validate and focuses it', async () => {
-    render(<ConfigStudio url={pageUrl} token="tok" />);
+    renderStudio();
 
     const items = screen.getByLabelText(COPY.itemsSelector);
     expect(screen.getByRole('button', { name: COPY.previewExtraction })).toBeDisabled();
@@ -44,7 +49,7 @@ describe('ConfigStudio', () => {
 
   it('adds an attribute, chooses an extractor, and adds then removes a post-processor', async () => {
     echoValidate();
-    render(<ConfigStudio url={pageUrl} token="tok" />);
+    renderStudio();
 
     fireEvent.click(screen.getByRole('button', { name: COPY.addAttribute }));
     fireEvent.input(screen.getByLabelText(COPY.attributeName), { target: { value: 'title' } });
@@ -82,7 +87,7 @@ describe('ConfigStudio', () => {
       )
     );
 
-    render(<ConfigStudio url={pageUrl} token="tok" />);
+    renderStudio();
     fireEvent.click(screen.getByRole('button', { name: COPY.applySuggestion }));
 
     await waitFor(() => expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('.post'));
@@ -108,7 +113,7 @@ describe('ConfigStudio', () => {
       )
     );
 
-    render(<ConfigStudio url={pageUrl} token="tok" />);
+    renderStudio();
     const preview = screen.getByRole('button', { name: COPY.previewExtraction });
     await waitFor(() => expect(preview).toBeEnabled());
     fireEvent.click(preview);
@@ -116,4 +121,16 @@ describe('ConfigStudio', () => {
     await waitFor(() => expect(screen.getByText('Sample headline')).toBeInTheDocument());
     expect(screen.getByText(COPY.previewItemCount(1))).toBeInTheDocument();
   });
+
+  it('sends the validated selectors when generating a feed', async () => {
+    const onGenerate = renderStudio();
+    const save = screen.getByRole('button', { name: COPY.saveAndGenerate });
+    expect(save).toBeDisabled();
+    await waitFor(() => expect(save).toBeEnabled());
+
+    fireEvent.click(save);
+
+    await waitFor(() => expect(onGenerate).toHaveBeenCalled());
+    expect(onGenerate.mock.calls[0]?.[0]).toMatchObject({ items: { selector: 'article', enhance: false } });
+  });
 });
diff --git a/frontend/src/components/App.tsx b/frontend/src/components/App.tsx
index 3a40302f..88186158 100644
--- a/frontend/src/components/App.tsx
+++ b/frontend/src/components/App.tsx
@@ -63,6 +63,7 @@ export function App() {
     onCancelTokenPrompt,
     onRetryCreate,
     onCreateAnother,
+    generateFromStudio,
     onRefine,
     onRetryPreview,
     sourceUrl,
@@ -113,7 +114,7 @@ export function App() {
       />
     );
   } else if (viewModel.kind === 'refine') {
-    bodyContent = <ConfigStudio url={sourceUrl} token={token ?? ''} />;
+    bodyContent = <ConfigStudio url={sourceUrl} token={token ?? ''} onGenerate={generateFromStudio} />;
   } else {
     bodyContent = (
       <CreateFeedPanel
diff --git a/frontend/src/components/ConfigStudio.tsx b/frontend/src/components/ConfigStudio.tsx
index 9cc7c006..6b2d8b03 100644
--- a/frontend/src/components/ConfigStudio.tsx
+++ b/frontend/src/components/ConfigStudio.tsx
@@ -15,16 +15,20 @@ import {
 } from '../studio/selectorDraft';
 import { hasSyntaxError, studioIssues, useStudio, type StudioState } from '../studio/useStudio';
 
+const STUDIO_BUSY_PHASES = new Set<StudioState['phase']>(['validating', 'previewing', 'saving']);
+
 interface ConfigStudioProperties {
   readonly url: string;
   readonly token: string;
+  readonly onGenerate: (selectors: Record<string, unknown>) => Promise<void>;
 }
 
-export function ConfigStudio({ url, token }: ConfigStudioProperties) {
+export function ConfigStudio({ url, token, onGenerate }: ConfigStudioProperties) {
   const studio = useStudio({ url, token });
   const { state, suggestion } = studio;
   const canPreview = (state.phase === 'editing' && state.validated) || state.phase === 'previewed';
-  const isBusy = state.phase === 'validating' || state.phase === 'previewing';
+  const canSave = canPreview;
+  const isBusy = STUDIO_BUSY_PHASES.has(state.phase);
   const itemsReference = useRef<HTMLInputElement>(null);
 
   useEffect(() => {
@@ -67,10 +71,25 @@ export function ConfigStudio({ url, token }: ConfigStudioProperties) {
         </label>
 
         <div class="ui-actions">
+          <button
+            type="button"
+            class="btn btn--primary"
+            disabled={!canSave}
+            onClick={() => {
+              void studio.save(onGenerate);
+            }}
+          >
+            {state.phase === 'saving' ? COPY.creating : COPY.saveAndGenerate}
+          </button>
           <button type="button" class="btn btn--quiet" onClick={() => studio.requestSuggestion()}>
             {COPY.applySuggestion}
           </button>
-          <button type="button" class="btn" disabled={!canPreview} onClick={() => studio.requestPreview()}>
+          <button
+            type="button"
+            class="btn btn--ghost"
+            disabled={!canPreview}
+            onClick={() => studio.requestPreview()}
+          >
             {state.phase === 'previewing' ? COPY.previewChecking : COPY.previewExtraction}
           </button>
         </div>
diff --git a/frontend/src/feed/useFeedCreation.ts b/frontend/src/feed/useFeedCreation.ts
index 360ac7f5..f8a38ab0 100644
--- a/frontend/src/feed/useFeedCreation.ts
+++ b/frontend/src/feed/useFeedCreation.ts
@@ -39,14 +39,14 @@ export function useFeedCreation() {
     []
   );
 
-  async function createFeed(normalizedUrl: string, token: string) {
+  async function createFeed(normalizedUrl: string, token: string, selectors?: Record<string, unknown>) {
     const requestId = requestIdReference.current + 1;
     requestIdReference.current = requestId;
     cancelPreview();
     setState((previous) => ({ ...previous, isCreating: true, error: undefined }));
 
     try {
-      const feed = await requestFeedCreation(normalizedUrl, token);
+      const feed = await requestFeedCreation(normalizedUrl, token, selectors);
       const result = buildCreatedFeedResult(feed);
       commitResult(result, requestId, setState, requestIdReference);
       void hydrateFeedPreview(feed, requestId, setState, requestIdReference, previewAbortControllerReference);
diff --git a/frontend/src/feed/useFeedFlow.ts b/frontend/src/feed/useFeedFlow.ts
index 23cf8105..0fb8de86 100644
--- a/frontend/src/feed/useFeedFlow.ts
+++ b/frontend/src/feed/useFeedFlow.ts
@@ -4,6 +4,7 @@ import { decideJourney } from './decideJourney';
 import { clearFeedDraftState, loadFeedDraftState, saveFeedDraftState } from '../utils/feedWorkflowStorage';
 import { expandCreateUrl } from '../utils/url';
 import type { FeedCreationError } from '../api/contracts';
+import { isFeedCreationError } from '../feeds/feedsService';
 import { COPY } from '../journey/copy';
 import type { AppRoute } from '../routes/appRoute';
 import type { MayCreateResult } from '../session';
@@ -241,6 +242,35 @@ export function useFeedFlow({
   }, [clearError, clearResult, createEntryKey, feedFieldErrors.form, route]);
 
   const sourceUrl = inMemorySourceUrl(feedFormData.url, result?.feed.url);
+
+  const generateFromStudio = async (selectors: Record<string, unknown>) => {
+    const expanded = expandCreateUrl(sourceUrl);
+    if ('error' in expanded) {
+      throw new Error(expanded.error === 'empty' ? COPY.urlRequired : COPY.invalidUrlFormat);
+    }
+
+    try {
+      const createdResult = await createFeed(expanded.ok, token ?? '', selectors);
+      clearFeedDraftState();
+      navigate({ kind: 'result', feedToken: createdResult.feed.feed_token });
+      setTokenError('');
+    } catch (submitError) {
+      if (!isFeedCreationError(submitError)) throw submitError;
+
+      if (submitError.kind === 'auth' || submitError.nextAction === 'enter_token') {
+        clearToken();
+        clearError();
+        setTokenDraft('');
+        if (route.kind !== 'token') navigate({ kind: 'token', prefillUrl: expanded.ok });
+        setTokenError(COPY.tokenRejected);
+        return;
+      }
+
+      clearError();
+      throw submitError;
+    }
+  };
+
   const viewModel = decideJourney({
     creationError,
     feedFieldErrors,
@@ -289,6 +319,7 @@ export function useFeedFlow({
     onRefine: () => {
       navigate({ kind: 'refine' });
     },
+    generateFromStudio,
     onRetryPreview: retryPreviewFetch,
     sourceUrl,
     setBookmarkletNotice,
diff --git a/frontend/src/feeds/feedsService.ts b/frontend/src/feeds/feedsService.ts
index f207b385..a6cae969 100644
--- a/frontend/src/feeds/feedsService.ts
+++ b/frontend/src/feeds/feedsService.ts
@@ -31,11 +31,18 @@ interface RawFeedApiResponse extends RawApiResponse {
   data?: RawFeedPayload;
 }
 
-export async function requestFeedCreation(url: string, token: string): Promise<FeedRecord> {
+export async function requestFeedCreation(
+  url: string,
+  token: string,
+  selectors?: Record<string, unknown>
+): Promise<FeedRecord> {
+  const body: { url: string; selectors?: Record<string, unknown> } = { url };
+  if (selectors) body.selectors = selectors;
+
   const response = await fetch(resolveApiUrl('feeds'), {
     method: 'POST',
     headers: buildCreateHeaders(token),
-    body: JSON.stringify({ url }),
+    body: JSON.stringify(body),
   });
 
   const payload = await readJsonResponse<RawFeedApiResponse>(response);
diff --git a/frontend/src/journey/copy.ts b/frontend/src/journey/copy.ts
index 4e32b2b5..346a5ac8 100644
--- a/frontend/src/journey/copy.ts
+++ b/frontend/src/journey/copy.ts
@@ -85,6 +85,7 @@ export const COPY = {
   postProcessors: 'Post-processors',
   addPostProcessor: 'Add post-processor',
   previewExtraction: 'Preview',
+  saveAndGenerate: 'Save and generate feed',
   yamlConfig: 'YAML',
   yamlSyntax: 'YAML could not be parsed.',
   pattern: 'Pattern',
diff --git a/frontend/src/studio/useStudio.ts b/frontend/src/studio/useStudio.ts
index c91c1d4d..315a080b 100644
--- a/frontend/src/studio/useStudio.ts
+++ b/frontend/src/studio/useStudio.ts
@@ -1,5 +1,5 @@
 import { useEffect, useRef, useState } from 'preact/hooks';
-import { isAbortError } from '../feeds/feedsService';
+import { isAbortError, isFeedCreationError } from '../feeds/feedsService';
 import { COPY } from '../journey/copy';
 import {
   previewStudioFeed,
@@ -45,6 +45,7 @@ export type StudioState =
   | (StudioDocument & { readonly phase: 'invalid'; readonly issues: readonly StudioIssue[] })
   | (StudioDocument & { readonly phase: 'previewing' })
   | (StudioDocument & { readonly phase: 'previewed'; readonly preview: StudioPreview })
+  | (StudioDocument & { readonly phase: 'saving' })
   | (StudioDocument & { readonly phase: 'failed'; readonly message: string });
 
 type EditSource = 'selectors' | 'yaml';
@@ -71,6 +72,7 @@ export function useStudio({ url, token, validateDelayMs = STUDIO_VALIDATE_DELAY_
   const requestIdReference = useRef(0);
   const previewRequestReference = useRef(0);
   const suggestRequestReference = useRef(0);
+  const saveRequestReference = useRef(0);
 
   useEffect(() => {
     const requestId = ++requestIdReference.current;
@@ -251,6 +253,24 @@ export function useStudio({ url, token, validateDelayMs = STUDIO_VALIDATE_DELAY_
     }
   }
 
+  async function save(create: (selectors: Record<string, unknown>) => Promise<void>) {
+    const requestId = ++saveRequestReference.current;
+    const current = stateReference.current;
+    setState({ phase: 'saving', draft: current.draft, yaml: current.yaml });
+
+    try {
+      await create(selectorsFromDraft(current.draft));
+    } catch (error) {
+      if (saveRequestReference.current !== requestId) return;
+      setState({
+        phase: 'failed',
+        draft: current.draft,
+        yaml: current.yaml,
+        message: failureMessage(error),
+      });
+    }
+  }
+
   return {
     state,
     suggestion,
@@ -271,6 +291,7 @@ export function useStudio({ url, token, validateDelayMs = STUDIO_VALIDATE_DELAY_
       void requestSuggestion();
     },
     selectorsDocument: () => selectorsFromDraft(stateReference.current.draft),
+    save,
   };
 }
 
@@ -281,3 +302,8 @@ export function studioIssues(state: StudioState): readonly StudioIssue[] {
 export function hasSyntaxError(state: StudioState): boolean {
   return state.phase === 'invalid' && state.issues.some((issue) => issue.code === 'parse');
 }
+
+function failureMessage(error: unknown): string {
+  if (isFeedCreationError(error) || error instanceof Error) return error.message;
+  return COPY.unableToCompleteCreation;
+}

From 70c799af8c390d991bd536b1539ef81b589ea963 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sat, 19 Sep 2026 23:37:16 +0200
Subject: [PATCH 016/108] fix(security): validate token selectors only after
 the HMAC check

FeedToken::Codec.decode rebuilt the signed selectors through
RefinedSelectors.from_wire, which ran Html2rss::Config.validate. That put the
full gem validator behind an unauthenticated, unsigned wire document: any
caller could drive it by putting a selectors subtree in a forged token.
Measured 0.004ms for a plain bad token against 0.218ms for an 808-byte forged
one carrying 60 selectors, a 58x amplification before a single HMAC byte is
compared.

Split the build so decode runs the structural allowlist only (denied keys,
shape, wire cap) and the schema check moves behind verification.
SourceResolver now calls from_verified_wire, which it only reaches after
authorize_feed_token! has checked the signature, so the defence-in-depth
re-validation is kept without exposing it pre-auth.
---
 app/web/feeds/source_resolver.rb      |  5 ++++-
 app/web/security/refined_selectors.rb | 23 ++++++++++++++++++-----
 2 files changed, 22 insertions(+), 6 deletions(-)

diff --git a/app/web/feeds/source_resolver.rb b/app/web/feeds/source_resolver.rb
index 9b55fb3e..79a438d8 100644
--- a/app/web/feeds/source_resolver.rb
+++ b/app/web/feeds/source_resolver.rb
@@ -75,6 +75,9 @@ def build_token_source(feed_request, feed_token)
             )
           end
 
+          # Re-runs the full allowlist, including schema validation, against the wire
+          # document. Reached only after {#authorize_feed_token!} verified the signature.
+          #
           # @param feed_token [Html2rss::Web::FeedToken]
           # @return [Hash{Symbol=>Object}]
           def expanded_generator_input(feed_token)
@@ -82,7 +85,7 @@ def expanded_generator_input(feed_token)
             GeneratorInput.for_token(
               url: feed_token.url,
               strategy: resolved_strategy(feed_token),
-              selectors: selectors.nil? ? nil : RefinedSelectors.from_wire(selectors.to_wire)
+              selectors: selectors.nil? ? nil : RefinedSelectors.from_verified_wire(selectors.to_wire)
             )
           end
 
diff --git a/app/web/security/refined_selectors.rb b/app/web/security/refined_selectors.rb
index 00011c6a..2d947b67 100644
--- a/app/web/security/refined_selectors.rb
+++ b/app/web/security/refined_selectors.rb
@@ -70,24 +70,37 @@ class << self
         # @param hash [Hash] client object; only +selectors+ is permitted
         # @return [Html2rss::Web::RefinedSelectors]
         # @raise [Html2rss::Web::BadRequestError] when the fragment is not allowlisted
-        def from_client(hash) = build(hash)
+        def from_client(hash) = build(hash, validate_shape: true)
 
         ##
-        # Rebuilds refined selectors from a decoded token wire document.
+        # Rebuilds refined selectors from a decoded but *unverified* token wire document.
+        #
+        # Runs the structural allowlist only. Schema validation is withheld until the
+        # HMAC has been checked, so an unauthenticated caller cannot drive the gem
+        # validator with an unsigned token. {.from_verified_wire} runs it afterwards.
+        #
+        # @param hash [Hash] wire object previously returned by {#to_wire}
+        # @return [Html2rss::Web::RefinedSelectors]
+        # @raise [Html2rss::Web::BadRequestError] when the fragment is not allowlisted
+        def from_wire(hash) = build(hash, validate_shape: false)
+
+        ##
+        # Rebuilds refined selectors from a wire document whose signature already verified.
         #
         # @param hash [Hash] wire object previously returned by {#to_wire}
         # @return [Html2rss::Web::RefinedSelectors]
         # @raise [Html2rss::Web::BadRequestError] when the fragment is not allowlisted
-        def from_wire(hash) = build(hash)
+        def from_verified_wire(hash) = build(hash, validate_shape: true)
 
         private
 
         # @param hash [Object]
+        # @param validate_shape [Boolean]
         # @return [Html2rss::Web::RefinedSelectors]
-        def build(hash)
+        def build(hash, validate_shape:)
           selectors = permitted_selectors(normalized_fragment(hash))
           enforce_wire_limit!(selectors)
-          validate_shape!(selectors)
+          validate_shape!(selectors) if validate_shape
           new(selectors:)
         end
 

From d4578219539f6bdb8c5703c1c7769b3ea3084568 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sat, 19 Sep 2026 23:37:33 +0200
Subject: [PATCH 017/108] fix(security): bound the feed-token wire before
 inflating it

Codec.decode inflated whatever arrived on the token route with no cap on
either the encoded input or the inflated output. Auth.extract_token's 1024
byte limit only guards the Authorization header, not the path segment, so a
26KB token expanded to 20,000,060 bytes in 55ms for an unauthenticated
caller: a 769x memory amplification per request.

Reject encoded tokens over MAX_ENCODED_BYTES and inflate in chunks, aborting
at MAX_INFLATED_BYTES. The abort raises Zlib::DataError, which decode already
rescues, so an oversized token still fails closed as 401 rather than
surfacing a new error shape.
---
 app/web/security/feed_token.rb | 27 ++++++++++++++++++++++++++-
 1 file changed, 26 insertions(+), 1 deletion(-)

diff --git a/app/web/security/feed_token.rb b/app/web/security/feed_token.rb
index 2e947c6e..528e9a70 100644
--- a/app/web/security/feed_token.rb
+++ b/app/web/security/feed_token.rb
@@ -40,6 +40,12 @@ def valid_for_url?(candidate_url)
 
     class FeedToken
       DEFAULT_EXPIRY = 315_360_000
+      # Largest encoded token accepted from the wire. A token carrying the maximum
+      # signed selectors subtree stays well under this.
+      MAX_ENCODED_BYTES = 4_096
+      # Hard cap on the inflated wire document so an unauthenticated caller cannot
+      # trade a small token for a large allocation.
+      MAX_INFLATED_BYTES = 16_384
 
       ##
       # zlib + URL-safe Base64 codec for feed-token wire payloads.
@@ -56,6 +62,7 @@ def encode(token)
           # @return [Html2rss::Web::FeedToken, nil]
           def decode(encoded_token)
             return unless encoded_token
+            return if encoded_token.bytesize > MAX_ENCODED_BYTES
 
             token_data = parse_token_data(encoded_token)
             return unless valid_token_data?(token_data)
@@ -79,10 +86,28 @@ def wire_document(token)
           # @param encoded_token [String]
           # @return [Hash{Symbol=>Object}]
           def parse_token_data(encoded_token)
-            inflated = Zlib::Inflate.inflate(Base64.urlsafe_decode64(encoded_token))
+            inflated = inflate_bounded(Base64.urlsafe_decode64(encoded_token))
             JSON.parse(inflated, symbolize_names: true)
           end
 
+          # Inflates in chunks and aborts once {MAX_INFLATED_BYTES} is exceeded, so a
+          # compression bomb is discarded instead of being fully expanded.
+          #
+          # @param compressed [String]
+          # @return [String]
+          # @raise [Zlib::DataError] when the document inflates past the cap
+          def inflate_bounded(compressed)
+            stream = Zlib::Inflate.new
+            buffer = +''
+            stream.inflate(compressed) do |chunk|
+              buffer << chunk
+              raise Zlib::DataError, 'token payload exceeds the inflate cap' if buffer.bytesize > MAX_INFLATED_BYTES
+            end
+            buffer
+          ensure
+            stream.close
+          end
+
           # @param token_data [Hash{Symbol=>Object}]
           # @return [Html2rss::Web::FeedToken]
           def decoded_token(token_data)

From fda395061cf6ac7fb0b9ee702bc34252ece8cf73 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sat, 19 Sep 2026 23:37:33 +0200
Subject: [PATCH 018/108] fix(config): fail feature flags closed when RACK_ENV
 is unset

Flags.development_or_test? defaulted a missing RACK_ENV to "development",
while EnvironmentValidator.non_production? treats the same state as
production. A deployment that forgot the variable therefore got production
secret-key enforcement but silently enabled STUDIO_ENABLED and
AUTO_SOURCE_ENABLED, exposing the studio and live-fetch surfaces.

Treat unset as not-development so both flags default off. Every real
entrypoint sets RACK_ENV explicitly (docker-compose, bin/dev*, the dev
container, and spec_helper), so no supported workflow changes.
---
 app/web/config/flags.rb | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/app/web/config/flags.rb b/app/web/config/flags.rb
index 10b85497..e633f56d 100644
--- a/app/web/config/flags.rb
+++ b/app/web/config/flags.rb
@@ -203,9 +203,13 @@ def validate_unknown_feature_keys!
           raise ArgumentError, "Unknown feature flags: #{unknown.sort.join(', ')}"
         end
 
+        # An unset RACK_ENV is not development. {EnvironmentValidator} already treats
+        # it as production, so defaulting it to development here would open the studio
+        # and live-fetch surfaces on a deployment that merely forgot the variable.
+        #
         # @return [Boolean]
         def development_or_test?
-          DEV_OR_TEST_ENVS.include?(ENV.fetch('RACK_ENV', 'development'))
+          DEV_OR_TEST_ENVS.include?(ENV.fetch('RACK_ENV', nil))
         end
       end
     end

From f869a0c0466dbe3b0f2ea4df212bd99c4c25e7b0 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sat, 19 Sep 2026 23:37:33 +0200
Subject: [PATCH 019/108] fix(request): stop buffering request bodies in the
 context middleware

build_context read request.params, and Rack::Request#params parses POST for
form-encoded requests, which buffers the entire body. The middleware runs
before RateLimiter and before every handler's MAX_BODY_BYTES gate, so a
200KB form POST to a studio route was fully read into memory and only then
rejected with 400. The new routes' body limit was effectively decorative
against that content type.

Read the query string instead. The strategy parameter this line wants has
always been a query parameter on feed URLs, so the recorded context is
unchanged for every real caller.
---
 app/web/request/request_context_middleware.rb | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/app/web/request/request_context_middleware.rb b/app/web/request/request_context_middleware.rb
index 745eecb8..3f2819c1 100644
--- a/app/web/request/request_context_middleware.rb
+++ b/app/web/request/request_context_middleware.rb
@@ -51,6 +51,9 @@ def route_group_for(path)
         'static'
       end
 
+      # Reads the query string only. Touching +params+ would make Rack buffer the
+      # whole request body here, ahead of rate limiting and every handler body cap.
+      #
       # @param request [Rack::Request]
       # @return [Html2rss::Web::RequestContext::Context]
       def build_context(request)
@@ -61,7 +64,7 @@ def build_context(request)
           http_method: request.request_method.to_s.upcase,
           route_group: route_group_for(path),
           actor: nil,
-          strategy: request.params['strategy'],
+          strategy: request.GET['strategy'],
           started_at: Time.now.utc.iso8601
         )
       end

From 60a5a19dc0e319752bfd16f6e489db82ecd5688a Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sat, 19 Sep 2026 23:37:33 +0200
Subject: [PATCH 020/108] fix(observability): keep studio route names out of
 token redaction

FEED_TOKEN_ROUTE matches any single segment under /api/v1/feeds/, so the
studio routes logged as /api/v1/feeds/[REDACTED]. Validate, preview, and
suggest_selectors calls became indistinguishable in the audit trail, which
removes the evidence needed to investigate abuse of exactly the endpoints
that trigger upstream fetches.

Skip redaction for segments the router mounts by name. The list is read from
FeedRoutes::STUDIO_POSTS so the router stays the single owner and a future
studio route cannot drift out of the audit trail.
---
 app/web/security/log_sanitizer.rb | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

diff --git a/app/web/security/log_sanitizer.rb b/app/web/security/log_sanitizer.rb
index 7c403ddd..5d656adb 100644
--- a/app/web/security/log_sanitizer.rb
+++ b/app/web/security/log_sanitizer.rb
@@ -12,12 +12,18 @@ module LogSanitizer
       PATH_KEYS = Set['endpoint', 'path'].freeze
 
       class << self
+        # Redacts the feed-token segment while keeping named sub-routes readable, so
+        # studio calls stay attributable in the audit trail.
+        #
         # @param path [String, nil]
         # @return [String, nil]
         def sanitize_path(path)
           return if path.nil?
 
-          path.to_s.gsub(FEED_TOKEN_ROUTE, '\1[REDACTED]\3')
+          path.to_s.gsub(FEED_TOKEN_ROUTE) do
+            prefix, segment, extension = Regexp.last_match.captures
+            named_feed_route?(segment) ? Regexp.last_match(0) : "#{prefix}[REDACTED]#{extension}"
+          end
         end
 
         # @param details [Hash]
@@ -30,6 +36,15 @@ def sanitize_details(details)
 
         private
 
+        # Route names are owned by the router; asking it keeps one list of
+        # non-token segments under +/api/v1/feeds+.
+        #
+        # @param segment [String, nil]
+        # @return [Boolean]
+        def named_feed_route?(segment)
+          Routes::ApiV1::FeedRoutes::STUDIO_POSTS.key?(segment)
+        end
+
         # @param key [Object]
         # @param value [Object]
         # @return [Object]

From 63156e6e3d1ea2a1190cb7782638cf45e855e9de Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sat, 19 Sep 2026 23:37:50 +0200
Subject: [PATCH 021/108] fix(api): report studio schema failures through a
 typed error

ValidateConfig told a schema failure apart from an allowlist rejection by
testing whether the exception message contained " [", the separator in
ValidationIssue#to_s. Root keys are echoed into the rejection message, so a
caller chose which branch ran by naming a key: POST /api/v1/feeds/validate
with a yaml root key of "foo [bar" returned 200 and report.success=true for
a config the create endpoint rejects, while "channel" and "request"
correctly returned 400. Validate and execute disagreed on the same input.

Raise RefinedSelectors::SchemaInvalid carrying the report, and rescue that
type instead of parsing a message. The rescue also stops re-validating: the
report it already has is returned directly.

assess now forwards the whole body rather than only body["selectors"], so a
denied sibling key is rejected on the JSON path as it already was on the
YAML path. The frontend only ever sends {selectors} or {yaml}, so no client
request shape changes.
---
 app/web/api/v1/validate_config.rb     | 11 ++++++-----
 app/web/security/refined_selectors.rb | 19 ++++++++++++++++++-
 2 files changed, 24 insertions(+), 6 deletions(-)

diff --git a/app/web/api/v1/validate_config.rb b/app/web/api/v1/validate_config.rb
index d1a3ef38..abd3c75a 100644
--- a/app/web/api/v1/validate_config.rb
+++ b/app/web/api/v1/validate_config.rb
@@ -67,7 +67,7 @@ def assess(body)
               return assess_yaml(body['yaml']) if body.key?('yaml') && !body['yaml'].nil?
               raise BadRequestError, 'yaml or selectors is required' unless body.key?('selectors')
 
-              assess_fragment({ selectors: body['selectors'] })
+              assess_fragment(body)
             end
 
             # @param yaml [Object]
@@ -78,16 +78,17 @@ def assess_yaml(yaml)
               [Html2rss::Config::IssueMapper.parse_failure(error.message), nil]
             end
 
+            # A schema failure is a reportable outcome; anything else the allowlist
+            # rejects (denied or unknown root key, oversized wire) stays a 400.
+            #
             # @param fragment [Hash]
             # @return [Array(Html2rss::Config::ValidationReport, Hash, nil)]
             def assess_fragment(fragment)
               refined = RefinedSelectors.from_client(fragment)
               [validation_report(refined.selectors), refined.selectors]
-            rescue BadRequestError => error
-              raise unless error.message.include?(' [')
-
+            rescue RefinedSelectors::SchemaInvalid => error
               selectors = fragment.is_a?(Hash) ? fragment[:selectors] || fragment['selectors'] : nil
-              [validation_report(selectors), selectors.is_a?(Hash) ? selectors : nil]
+              [error.report, selectors.is_a?(Hash) ? selectors : nil]
             end
 
             # @param selectors [Hash, nil]
diff --git a/app/web/security/refined_selectors.rb b/app/web/security/refined_selectors.rb
index 2d947b67..8faebb7c 100644
--- a/app/web/security/refined_selectors.rb
+++ b/app/web/security/refined_selectors.rb
@@ -51,6 +51,22 @@ def deep_freeze(value)
     end
 
     class RefinedSelectors
+      ##
+      # Raised when a fragment clears the allowlist but fails gem schema validation.
+      #
+      # Carries the report so callers can render issues without re-validating or
+      # inspecting the exception message.
+      class SchemaInvalid < BadRequestError
+        # @return [Html2rss::Config::ValidationReport]
+        attr_reader :report
+
+        # @param report [Html2rss::Config::ValidationReport]
+        def initialize(report)
+          @report = report
+          super(report.to_s)
+        end
+      end
+
       # Root keys a client fragment may contain. Published schema reads this set.
       ALLOWED_KEYS = Set[:selectors].freeze
       # Root keys rejected by name so the error is not a generic invalid-config.
@@ -142,11 +158,12 @@ def enforce_wire_limit!(selectors)
 
         # @param selectors [Hash{Symbol=>Object}]
         # @return [void]
+        # @raise [Html2rss::Web::RefinedSelectors::SchemaInvalid]
         def validate_shape!(selectors)
           report = Html2rss::Config.validate({ channel: { url: VALIDATION_CHANNEL_URL }, selectors: })
           return if report.success?
 
-          raise BadRequestError, report.to_s
+          raise SchemaInvalid, report
         end
 
         # @param value [Object]

From 64cb7f8dbf68e0686a8458b38859aa92ce0310a1 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sat, 19 Sep 2026 23:37:51 +0200
Subject: [PATCH 022/108] fix(api): authenticate studio requests before
 disclosing flag state

All three studio handlers checked Flags.studio_enabled? and
Flags.auto_source_enabled? before Auth.authenticate, so an anonymous POST
was answered with 403 "Studio is disabled" or 403 "Auto source feature is
disabled". That hands an unauthenticated caller the deployment's feature
configuration and tells them which instances are worth probing further.

Authenticate first, then evaluate the flags, so an anonymous caller only
ever sees 401.
---
 app/web/api/v1/preview_feed.rb      | 7 ++++---
 app/web/api/v1/suggest_selectors.rb | 7 ++++---
 app/web/api/v1/validate_config.rb   | 4 +++-
 3 files changed, 11 insertions(+), 7 deletions(-)

diff --git a/app/web/api/v1/preview_feed.rb b/app/web/api/v1/preview_feed.rb
index 30cf07d4..4f1f8f4e 100644
--- a/app/web/api/v1/preview_feed.rb
+++ b/app/web/api/v1/preview_feed.rb
@@ -26,14 +26,15 @@ def call(request)
 
             private
 
+            # Authenticates first so an anonymous caller cannot probe flag state.
+            #
             # @param request [Rack::Request]
             # @return [Hash]
             def live_account(request)
-              raise ForbiddenError, 'Studio is disabled' unless Flags.studio_enabled?
-              raise AutoSourceDisabledError unless Flags.auto_source_enabled?
-
               account = Auth.authenticate(request)
               raise UnauthorizedError, 'Authentication required' unless account
+              raise ForbiddenError, 'Studio is disabled' unless Flags.studio_enabled?
+              raise AutoSourceDisabledError unless Flags.auto_source_enabled?
 
               account
             end
diff --git a/app/web/api/v1/suggest_selectors.rb b/app/web/api/v1/suggest_selectors.rb
index 219ef42a..242ee35d 100644
--- a/app/web/api/v1/suggest_selectors.rb
+++ b/app/web/api/v1/suggest_selectors.rb
@@ -29,14 +29,15 @@ def call(request)
 
             private
 
+            # Authenticates first so an anonymous caller cannot probe flag state.
+            #
             # @param request [Rack::Request]
             # @return [Hash]
             def live_account(request)
-              raise ForbiddenError, 'Studio is disabled' unless Flags.studio_enabled?
-              raise AutoSourceDisabledError unless Flags.auto_source_enabled?
-
               account = Auth.authenticate(request)
               raise UnauthorizedError, 'Authentication required' unless account
+              raise ForbiddenError, 'Studio is disabled' unless Flags.studio_enabled?
+              raise AutoSourceDisabledError unless Flags.auto_source_enabled?
 
               account
             end
diff --git a/app/web/api/v1/validate_config.rb b/app/web/api/v1/validate_config.rb
index abd3c75a..0a6bbf90 100644
--- a/app/web/api/v1/validate_config.rb
+++ b/app/web/api/v1/validate_config.rb
@@ -28,11 +28,13 @@ def call(request)
 
             private
 
+            # Authenticates first so an anonymous caller cannot probe flag state.
+            #
             # @param request [Rack::Request]
             # @return [void]
             def ensure_allowed!(request)
-              raise ForbiddenError, 'Studio is disabled' unless Flags.studio_enabled?
               raise UnauthorizedError, 'Authentication required' unless Auth.authenticate(request)
+              raise ForbiddenError, 'Studio is disabled' unless Flags.studio_enabled?
             end
 
             # @param request [Rack::Request]

From c054f86ec65d5f88736a3b51ba78750aa201f789 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sat, 19 Sep 2026 23:37:51 +0200
Subject: [PATCH 023/108] fix(api): bound the suggest_selectors items hint

items_selector was forwarded to Html2rss.capture with no length limit; a
5000 character hint reached the gem unchanged. The selector is client text
handed to a parser during a live fetch, and the handler maps no gem parse
failure, so anything raised there classifies as 500 rather than a client
error.

Cap the hint and reject an oversized one as 400.
---
 app/web/api/v1/suggest_selectors.rb | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/app/web/api/v1/suggest_selectors.rb b/app/web/api/v1/suggest_selectors.rb
index 242ee35d..de17f53c 100644
--- a/app/web/api/v1/suggest_selectors.rb
+++ b/app/web/api/v1/suggest_selectors.rb
@@ -12,6 +12,9 @@ module V1
         # +Html2rss.capture+ returns the first segment strategy that clears its
         # quality gate, not a candidate list.
         module SuggestSelectors
+          # Upper bound for the client-supplied items selector hint.
+          MAX_ITEMS_SELECTOR_LENGTH = 256
+
           class << self
             ##
             # @param request [Rack::Request]
@@ -80,8 +83,11 @@ def allowed_url(raw_url, account)
 
             # @param raw [Object]
             # @return [String, nil]
+            # @raise [Html2rss::Web::BadRequestError] when the hint exceeds the cap
             def hint(raw)
               text = raw.to_s.strip
+              raise BadRequestError, 'items_selector is too long' if text.length > MAX_ITEMS_SELECTOR_LENGTH
+
               text.empty? ? nil : text
             end
 

From 98ddd330974a775f839b5d5640b25b2620395e09 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sat, 19 Sep 2026 23:41:21 +0200
Subject: [PATCH 024/108] test(security): cover the studio auth chain abuse
 paths

Drives every example as a real Rack request through the full middleware
stack, so a gate bypassed at the middleware or routing layer still fails
here rather than passing against a unit stub of the gate.

Verified red before the fixes in this branch: 14 of 29 examples failed
against the pre-fix tree, covering pre-HMAC schema validation, the token
wire caps, the request-context body buffering, the " [" message sniff, the
denied root keys on the JSON validate path, the RACK_ENV flag default, the
flag-state disclosure, and the items_selector cap. All 29 pass after.

The remaining 15 are verification rather than regression: IDOR on serve,
preview, and suggest, username replay, tampered signed selectors with an
assertion that no fetch happened, expired tokens, and unauthenticated POSTs.
They passed before and after, and are kept so the behaviour is pinned.
---
 .../web/api/studio_auth_chain_spec.rb         | 262 ++++++++++++++++++
 1 file changed, 262 insertions(+)
 create mode 100644 spec/html2rss/web/api/studio_auth_chain_spec.rb

diff --git a/spec/html2rss/web/api/studio_auth_chain_spec.rb b/spec/html2rss/web/api/studio_auth_chain_spec.rb
new file mode 100644
index 00000000..b6f1ccbc
--- /dev/null
+++ b/spec/html2rss/web/api/studio_auth_chain_spec.rb
@@ -0,0 +1,262 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'base64'
+require 'climate_control'
+require 'json'
+require 'zlib'
+
+# Abuse-path coverage for the live auth chain behind the config studio.
+#
+# Every example drives a real Rack request through the full middleware stack, so
+# a gate that is bypassed at the middleware or routing layer still fails here.
+##
+# Rack input that records how many bytes anything upstream actually consumed.
+class CountingInput < StringIO
+  # @return [Integer]
+  attr_reader :bytes_read
+
+  # @param string [String]
+  def initialize(string)
+    super
+    @bytes_read = 0
+  end
+
+  # @return [String, nil]
+  def read(...)
+    super.tap { @bytes_read += it.to_s.bytesize }
+  end
+end
+
+RSpec.describe 'api/v1 studio auth chain', openapi: false, type: :request do
+  include Rack::Test::Methods
+
+  # Restricted account from config/feeds.yml; admin is allowlisted for "*".
+  let(:member_token) { 'CHANGE_ME_DEMO_TOKEN' }
+  let(:member_url) { 'https://news.ycombinator.com' }
+  let(:outside_url) { 'https://evil.example/articles' }
+  let(:selectors) { { items: { selector: 'article' } } }
+
+  def app = Html2rss::Web::App.freeze.app
+
+  def json_post(path, payload, token: nil)
+    header 'Authorization', "Bearer #{token}" if token
+    header 'Content-Type', 'application/json'
+    post path, payload.to_json
+  end
+
+  def error_message(response) = JSON.parse(response.body).dig('error', 'message')
+
+  # Signs a token directly so the example can bind a URL the create endpoint
+  # would have refused, which is the state left behind by an allowlist change.
+  def mint(username, url, selectors: nil, expires_in: 3600)
+    Html2rss::Web::Auth.generate_feed_token(username, url, selectors:, expires_in:)
+  end
+
+  def unpack(encoded) = JSON.parse(Zlib::Inflate.inflate(Base64.urlsafe_decode64(encoded)), symbolize_names: true)
+  def pack(document) = Base64.urlsafe_encode64(Zlib::Deflate.deflate(JSON.generate(document)))
+
+  describe 'broken access control' do
+    it 'refuses to serve a feed token bound to a URL outside the account allowlist' do
+      get "/api/v1/feeds/#{mint('demo', outside_url)}"
+
+      expect(last_response.status).to eq(403)
+    end
+
+    it 'refuses to preview a URL outside the account allowlist' do
+      json_post '/api/v1/feeds/preview', { url: outside_url, selectors: }, token: member_token
+
+      expect(last_response.status).to eq(403)
+      expect(error_message(last_response)).to eq('URL not allowed for this account')
+    end
+
+    it 'refuses to suggest selectors for a URL outside the account allowlist' do
+      json_post '/api/v1/feeds/suggest_selectors', { url: outside_url }, token: member_token
+
+      expect(last_response.status).to eq(403)
+      expect(error_message(last_response)).to eq('URL not allowed for this account')
+    end
+
+    it 'rejects a valid token replayed under another username' do
+      document = unpack(mint('demo', member_url))
+      document[:p][:u] = 'admin'
+
+      get "/api/v1/feeds/#{pack(document)}"
+
+      expect(last_response.status).to eq(401)
+    end
+
+    it 'does not reach a static feed by putting its name in the token route' do
+      get '/api/v1/feeds/example'
+
+      expect(last_response.status).to eq(401)
+    end
+  end
+
+  describe 'cryptographic integrity' do
+    before { allow(Html2rss).to receive(:feed_result).and_call_original }
+
+    it 'rejects a flipped byte in the signed selectors payload and never fetches', :aggregate_failures do
+      signed = mint('demo', member_url, selectors: Html2rss::Web::RefinedSelectors.from_client({ selectors: }))
+      document = unpack(signed)
+      document[:p][:c][:selectors][:items][:selector] = 'aRticle'
+
+      get "/api/v1/feeds/#{pack(document)}"
+
+      expect(last_response.status).to eq(401)
+      expect(Html2rss).not_to have_received(:feed_result)
+    end
+
+    it 'rejects an expired token' do
+      get "/api/v1/feeds/#{mint('demo', member_url, expires_in: -60)}"
+
+      expect(last_response.status).to eq(401)
+    end
+
+    it 'does not run gem schema validation before the signature check' do
+      allow(Html2rss::Config).to receive(:validate).and_call_original
+      unsigned = pack(
+        p: { u: 'demo', l: member_url, e: Time.now.to_i + 3600, c: { selectors: } },
+        s: 'forged-signature'
+      )
+
+      get "/api/v1/feeds/#{unsigned}"
+
+      expect(Html2rss::Config).not_to have_received(:validate)
+    end
+
+    it 'answers 401 rather than 500 for an undecodable token' do
+      get '/api/v1/feeds/not-a-token-at-all'
+
+      expect(last_response.status).to eq(401)
+    end
+  end
+
+  describe 'denial of service' do
+    it 'discards a compression bomb instead of inflating it', :aggregate_failures do
+      bomb = Base64.urlsafe_encode64(
+        Zlib::Deflate.deflate({ p: { u: 'demo', l: member_url, e: 1, pad: 'A' * 20_000_000 }, s: 'x' }.to_json, 9)
+      )
+
+      expect(Html2rss::Web::FeedToken::Codec.decode(bomb)).to be_nil
+      expect(bomb.bytesize).to be > Html2rss::Web::FeedToken::MAX_ENCODED_BYTES
+    end
+
+    it 'rejects an oversized encoded token' do
+      get "/api/v1/feeds/#{'A' * (Html2rss::Web::FeedToken::MAX_ENCODED_BYTES + 1)}"
+
+      expect(last_response.status).to eq(401)
+    end
+
+    it 'rejects an oversized form body without reading it', :aggregate_failures do
+      body = "x=#{'A' * (200 * 1024)}"
+      input = CountingInput.new(body)
+      status, = app.call(
+        Rack::MockRequest.env_for(
+          '/api/v1/feeds/validate',
+          method: 'POST', input:, 'CONTENT_TYPE' => 'application/x-www-form-urlencoded',
+          'CONTENT_LENGTH' => body.bytesize.to_s, 'HTTP_AUTHORIZATION' => "Bearer #{member_token}"
+        )
+      )
+
+      expect(body.bytesize).to be > Html2rss::Web::Api::V1::CreateFeed::MAX_BODY_BYTES
+      expect(status).to eq(400)
+      expect(input.bytes_read).to eq(0)
+    end
+
+    it 'rejects an oversized items_selector hint' do
+      json_post '/api/v1/feeds/suggest_selectors',
+                { url: member_url, items_selector: 'a' * 5_000 },
+                token: member_token
+
+      expect(last_response.status).to eq(400)
+      expect(error_message(last_response)).to eq('items_selector is too long')
+    end
+  end
+
+  describe 'server-side request forgery' do
+    %w[channel headers strategy request].each do |denied|
+      it "rejects a refined payload carrying #{denied}" do
+        json_post '/api/v1/feeds/validate',
+                  { denied => { 'url' => 'http://169.254.169.254/' }, 'selectors' => selectors },
+                  token: member_token
+
+        expect(last_response.status).to eq(400)
+        expect(error_message(last_response)).to eq("#{denied} is not allowed")
+      end
+    end
+
+    it 'keeps UrlValidator as the only decider of the fetched URL' do
+      token = mint('demo', member_url, selectors: Html2rss::Web::RefinedSelectors.from_client({ selectors: }))
+      resolved = Html2rss::Web::Feeds::SourceResolver.call(
+        Html2rss::Web::Feeds::Contracts::Request.new(target_kind: :token, feed_name: nil, token:, params: {})
+      )
+
+      expect(resolved.generator_input[:channel]).to eq(url: member_url)
+    end
+
+    it 'reports an allowlist rejection as 400 even when the key name mimics an issue line' do
+      json_post '/api/v1/feeds/validate',
+                { yaml: "foo [bar: 1\nselectors:\n  items:\n    selector: article\n" },
+                token: member_token
+
+      expect(last_response.status).to eq(400)
+      expect(error_message(last_response)).to eq('foo [bar is not allowed')
+    end
+
+    it 'still reports a schema failure as a structured issue', :aggregate_failures do
+      json_post '/api/v1/feeds/validate', { selectors: { items: { selector: 42 } } }, token: member_token
+
+      json = expect_success_response(last_response)
+      expect(json.dig('data', 'report', 'success')).to be(false)
+      expect(json.dig('data', 'report', 'issues')).not_to be_empty
+    end
+
+    it 'reports unparseable yaml as a parse issue rather than a 500' do
+      json_post '/api/v1/feeds/validate', { yaml: "selectors: [\n" }, token: member_token
+
+      expect(JSON.parse(last_response.body).dig('data', 'report', 'issues', 0, 'code')).to eq('parse')
+    end
+  end
+
+  describe 'authentication and misconfiguration' do
+    %w[feeds feeds/validate feeds/preview feeds/suggest_selectors].each do |path|
+      it "rejects an unauthenticated POST to /api/v1/#{path}" do
+        json_post "/api/v1/#{path}", { url: member_url, selectors: }
+
+        expect(last_response.status).to eq(401)
+      end
+    end
+
+    it 'authenticates before disclosing that the studio is disabled' do
+      ClimateControl.modify(STUDIO_ENABLED: 'false') do
+        json_post '/api/v1/feeds/validate', { selectors: }
+      end
+
+      expect(last_response.status).to eq(401)
+    end
+
+    it 'authenticates before disclosing that auto source is disabled' do
+      ClimateControl.modify(AUTO_SOURCE_ENABLED: 'false') do
+        json_post '/api/v1/feeds/preview', { url: member_url, selectors: }
+      end
+
+      expect(last_response.status).to eq(401)
+    end
+
+    it 'fails the studio and auto-source flags closed when RACK_ENV is unset', :aggregate_failures do
+      ClimateControl.modify(RACK_ENV: nil) do
+        expect(Html2rss::Web::Flags.studio_enabled?).to be(false)
+        expect(Html2rss::Web::Flags.auto_source_enabled?).to be(false)
+      end
+    end
+
+    it 'keeps studio route names readable in the audit trail', :aggregate_failures do
+      Html2rss::Web::Routes::ApiV1::FeedRoutes::STUDIO_POSTS.each_key do |name|
+        expect(Html2rss::Web::LogSanitizer.sanitize_path("/api/v1/feeds/#{name}")).to eq("/api/v1/feeds/#{name}")
+      end
+      expect(Html2rss::Web::LogSanitizer.sanitize_path("/api/v1/feeds/#{mint('demo', member_url)}"))
+        .to eq('/api/v1/feeds/[REDACTED]')
+    end
+  end
+end

From 47d8de2453085d2f904417d55fa859a9875a36fa Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sat, 19 Sep 2026 23:56:42 +0200
Subject: [PATCH 025/108] fix(deps): pin html2rss to a revision that bounds
 gsub patterns

The lock pinned revision 84cad9e9, which predates the gsub work. Without it a
client-authored `post_process: gsub` pattern reaches `Regexp.new` unbounded, so
the studio's selector path had no pattern-length or star-height ceiling.

Pin `ref: fc5de544`, the current html2rss master tip. That commit is the
squash-merge of PR #512, so the four branch commits (ec834ff7, b114e16c,
385c77cf, c7be5c83) are not literal ancestors of it; the trees are identical
instead (`git rev-parse c7be5c83^{tree} fc5de544^{tree}` both yield fa9d14e4),
which is the verifiable form of "master contains them". The installed gem
carries `Gsub::MAX_PATTERN_LENGTH` and `Config::IssueMapper`.

`branch: 'master'` is dropped because a floating branch silently re-resolves
those bounds on any later `bundle update`. The commented `gem 'html2rss',
'~> 0.30'` line is dropped too: uncommenting it resolves the released 0.30.0
gem, which has neither the gsub bounds nor `Config::IssueMapper`.
---
 Gemfile      | 6 ++++--
 Gemfile.lock | 4 ++--
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/Gemfile b/Gemfile
index 875094f5..892744c3 100644
--- a/Gemfile
+++ b/Gemfile
@@ -4,8 +4,10 @@ source 'https://rubygems.org'
 
 git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
 
-# gem 'html2rss', '~> 0.30'
-gem 'html2rss', github: 'html2rss/html2rss', branch: 'master'
+# Pinned by revision, not by branch: the studio needs the gsub pattern bounds and
+# Config::IssueMapper, which no released 0.30.x gem carries. Bump this ref
+# deliberately; do not swap it for `branch:` or for a rubygems version constraint.
+gem 'html2rss', github: 'html2rss/html2rss', ref: 'fc5de54409c1d5e4a36836365d2e7909a084626e'
 gem 'html2rss-configs', github: 'html2rss/html2rss-configs'
 
 # Use these instead of the two above (uncomment them) when developing locally:
diff --git a/Gemfile.lock b/Gemfile.lock
index 080b7013..11c7bb1f 100644
--- a/Gemfile.lock
+++ b/Gemfile.lock
@@ -1,7 +1,7 @@
 GIT
   remote: https://github.com/html2rss/html2rss
-  revision: 84cad9e9870e8159088c65e0b1a306e7f4ba9026
-  branch: master
+  revision: fc5de54409c1d5e4a36836365d2e7909a084626e
+  ref: fc5de54409c1d5e4a36836365d2e7909a084626e
   specs:
     html2rss (0.30.0)
       addressable (~> 2.7)

From 9adfa9648829f15539fe91673ab9317e1948573e Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 20 Sep 2026 00:08:59 +0200
Subject: [PATCH 026/108] fix(api): reject refined selectors when the studio is
 disabled
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`selectors_for` signed whatever `selectors` object the body carried and never
read `STUDIO_ENABLED`. The three studio POSTs honoured the kill switch, but
create did not, so an operator who turned the studio off could still be handed a
token whose signed `c:` document ran client-authored selectors — the flag closed
the door and left the window open.

Create now raises the same `403 Studio is disabled` the studio POSTs raise, but
only when the body actually carries `selectors`. A body without them stays the
automatic path and keeps working with the flag off, so ordinary URL-only create
is untouched.

The gate runs before the `AUTO_SOURCE_ENABLED` check so the refusal does not
depend on a second, unrelated flag. Authentication still runs first, so an
anonymous caller cannot probe flag state.

`require_account` collapses to one expression to stay under `Metrics/ClassLength`
without disabling the cop.
---
 AGENTS.md                     |  2 +-
 app/web/api/v1/create_feed.rb | 20 +++++++++++++-------
 docs/README.md                |  2 +-
 3 files changed, 15 insertions(+), 9 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 5fc5a093..2f4f3341 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -82,7 +82,7 @@ Token-holder refinement of the selectors subtree, then generate via create.
 | Item | Detail |
 | --- | --- |
 | Endpoints | `POST /api/v1/feeds/validate`, `POST /api/v1/feeds/preview`, `POST /api/v1/feeds/suggest_selectors` |
-| Create | `POST /api/v1/feeds` accepts optional `selectors` (same access token as validate) |
+| Create | `POST /api/v1/feeds` accepts optional `selectors` (same access token and flag as validate; URL-only create is unaffected by the flag) |
 | Flag | `STUDIO_ENABLED` (development/test default `true`; otherwise `false`) |
 | Disabled response | `403` when the flag is off |
 | Auth | Access token required on validate, preview, suggest, and create |
diff --git a/app/web/api/v1/create_feed.rb b/app/web/api/v1/create_feed.rb
index d01fc89b..4602f2d4 100644
--- a/app/web/api/v1/create_feed.rb
+++ b/app/web/api/v1/create_feed.rb
@@ -18,13 +18,21 @@ module CreateFeed # rubocop:disable Metrics/ModuleLength
             (?:[/?#].*)?\z
           }ix
 
-          # Allowlists an optional selectors object before it is signed. Absent keeps legacy tokens valid.
+          # Allowlists an optional selectors object before it is signed. Absent keeps legacy
+          # tokens valid and keeps create on the automatic path, which the studio flag does
+          # not gate. Present means the caller authored the selectors in the studio, so the
+          # same kill switch the studio POSTs enforce applies here.
           #
           # @param request [Rack::Request]
           # @return [Html2rss::Web::RefinedSelectors, nil]
+          # @raise [Html2rss::Web::ForbiddenError] when selectors are sent while the studio is disabled
           def self.selectors_for(request)
             raw = request_params(request)['selectors']
-            raw.nil? ? nil : RefinedSelectors.from_client({ selectors: raw })
+            return nil if raw.nil?
+
+            raise Html2rss::Web::ForbiddenError, 'Studio is disabled' unless Flags.studio_enabled?
+
+            RefinedSelectors.from_client({ selectors: raw })
           end
           private_class_method :selectors_for
 
@@ -48,10 +56,7 @@ def call(request)
             private
 
             def require_account(request)
-              account = Auth.authenticate(request)
-              raise Html2rss::Web::UnauthorizedError, 'Authentication required' unless account
-
-              account
+              Auth.authenticate(request) || raise(Html2rss::Web::UnauthorizedError, 'Authentication required')
             end
 
             def build_create_params(request, account)
@@ -131,9 +136,10 @@ def normalized_input_url(raw_url)
             # @param request [Rack::Request]
             # @return [Html2rss::Web::Api::V1::FeedMetadata::Metadata]
             def create_feed(params, account, request)
+              selectors = selectors_for(request)
               raise Html2rss::Web::AutoSourceDisabledError unless Flags.auto_source_enabled?
 
-              feed_token = Auth.generate_feed_token(account[:username], params.url, selectors: selectors_for(request))
+              feed_token = Auth.generate_feed_token(account[:username], params.url, selectors:)
               raise Html2rss::Web::InternalServerError, 'Failed to create feed' unless feed_token
 
               result = Feeds::Service.call(resolved_source_for(feed_token))
diff --git a/docs/README.md b/docs/README.md
index 32439dcd..f041f4ea 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -207,7 +207,7 @@ Rules:
 - `BUILD_TAG` and `GIT_SHA` are required in production so startup logs can identify the deployed build.
 - Add or change flags in code, tests, and this table together.
 
-`STUDIO_ENABLED=true` exposes the config refinement studio: `POST /api/v1/feeds/validate`, `POST /api/v1/feeds/preview`, and `POST /api/v1/feeds/suggest_selectors`. All three require a valid access token and return `403 Studio is disabled` when the flag is off. `preview` and `suggest_selectors` additionally need `AUTO_SOURCE_ENABLED=true` because they fetch the caller's URL live, and they only accept URLs the caller's account is allowed to reach. Leave the flag off in production unless you intend to let token holders run live extraction against arbitrary allowed URLs.
+`STUDIO_ENABLED=true` exposes the config refinement studio: `POST /api/v1/feeds/validate`, `POST /api/v1/feeds/preview`, and `POST /api/v1/feeds/suggest_selectors`. All three require a valid access token and return `403 Studio is disabled` when the flag is off. `POST /api/v1/feeds` returns the same `403` when the body carries a `selectors` object, because those selectors are studio output; a body without `selectors` stays the automatic path and keeps working with the flag off. `preview` and `suggest_selectors` additionally need `AUTO_SOURCE_ENABLED=true` because they fetch the caller's URL live, and they only accept URLs the caller's account is allowed to reach. Leave the flag off in production unless you intend to let token holders run live extraction against arbitrary allowed URLs.
 
 ---
 

From d9efc0fc61e39f5df8dd528697e5a093957ff4e3 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 20 Sep 2026 00:12:13 +0200
Subject: [PATCH 027/108] test: cover selector post-processors and the studio
 kill switch on create

Two behaviours the suite asserted nowhere.

`post_process: gsub` is the selector feature that carries a client-authored
regexp all the way to `Regexp.new`, so the allowlist spec now proves the pattern
survives minting, signing, and decoding intact, and that the gem's compile bound
(nested quantifiers, 256-character ceiling) surfaces as a 400 rather than a
pathological match. A denied root key travelling next to a post_process is still
rejected by name, so the post_process path does not widen the allowlist.

The create kill switch is HTTP behaviour, so it is covered with real Rack
requests next to the existing `AUTO_SOURCE_ENABLED` example: a `selectors` body
under `STUDIO_ENABLED=false` gets the same `403 Studio is disabled` as the studio
POSTs, and a URL-only body under the same flag still returns 201. Checked out
against the pre-fix `create_feed.rb` the first example fails (201 instead of 403)
and the second passes, so the pair discriminates the fix from the regression it
guards.

Both are `openapi: false`: they document flag states, not the published contract.
---
 spec/html2rss/web/api/v1_spec.rb              | 18 ++++++++++
 .../web/security/refined_selectors_spec.rb    | 33 +++++++++++++++++++
 2 files changed, 51 insertions(+)

diff --git a/spec/html2rss/web/api/v1_spec.rb b/spec/html2rss/web/api/v1_spec.rb
index 2bc274b4..a62b9e8f 100644
--- a/spec/html2rss/web/api/v1_spec.rb
+++ b/spec/html2rss/web/api/v1_spec.rb
@@ -798,6 +798,24 @@ def relative_feed_link_header(token)
       expect(json.dig('error', 'message')).to eq(Html2rss::Web::AutoSourceDisabledError::DEFAULT_MESSAGE)
     end
 
+    it 'rejects client-authored selectors while the studio is disabled', :aggregate_failures, openapi: false do
+      ClimateControl.modify(STUDIO_ENABLED: 'false') do
+        post_feed_request(url: feed_url, selectors: { items: { selector: 'article' } })
+      end
+
+      expect(last_response.status).to eq(403)
+      expect(JSON.parse(last_response.body).dig('error', 'message')).to eq('Studio is disabled')
+    end
+
+    it 'still creates a url-only feed while the studio is disabled', :aggregate_failures, openapi: false do
+      ClimateControl.modify(STUDIO_ENABLED: 'false', AUTO_SOURCE_ENABLED: 'true') do
+        post_feed_request(url: feed_url)
+      end
+
+      expect(last_response.status).to eq(201)
+      expect(expect_success_response(last_response).dig('data', 'feed', 'url')).to eq(feed_url)
+    end
+
     it 'returns 429 when rate limit is exceeded', :aggregate_failures do
       allow(Html2rss::Web::Flags).to receive_messages(
         rate_limit_enabled?: true,
diff --git a/spec/html2rss/web/security/refined_selectors_spec.rb b/spec/html2rss/web/security/refined_selectors_spec.rb
index 29e4ba7f..0fea35e6 100644
--- a/spec/html2rss/web/security/refined_selectors_spec.rb
+++ b/spec/html2rss/web/security/refined_selectors_spec.rb
@@ -6,6 +6,15 @@
   let(:selectors) { { items: { selector: 'article', enhance: true } } }
   let(:fragment) { { selectors: } }
 
+  # @param pattern [String]
+  # @return [Hash{Symbol=>Object}]
+  def selectors_with_gsub(pattern)
+    {
+      items: { selector: 'article' },
+      title: { selector: 'h2', post_process: [{ name: 'gsub', pattern:, replacement: ' ' }] }
+    }
+  end
+
   describe '.from_client and .from_wire' do
     it 'accepts an allowlisted selectors fragment and freezes the handoff', :aggregate_failures do
       refined = described_class.from_client(fragment)
@@ -73,4 +82,28 @@
         .to raise_error(Html2rss::Web::BadRequestError, /selectors\.items\.selector \[invalid_value\]/)
     end
   end
+
+  describe 'gsub post-processors' do
+    it 'admits a gsub pattern and carries it into the signed wire', :aggregate_failures do
+      refined = described_class.from_client(selectors: selectors_with_gsub('\\s+'))
+      encoded = Html2rss::Web::Auth.generate_feed_token('admin', 'https://example.com/feed', selectors: refined)
+
+      expect(refined.to_wire.dig(:selectors, :title, :post_process, 0, :pattern)).to eq('\\s+')
+      expect(Html2rss::Web::Auth.validate_and_decode_feed_token(encoded).selectors).to eq(refined)
+    end
+
+    it 'leaves the pattern bounds to the gem compile step', :aggregate_failures do
+      expect { described_class.from_client(selectors: selectors_with_gsub('(a+)+$')) }
+        .to raise_error(Html2rss::Web::BadRequestError, /pattern contains nested quantifiers/)
+      expect { described_class.from_client(selectors: selectors_with_gsub('a' * 300)) }
+        .to raise_error(Html2rss::Web::BadRequestError, /pattern exceeds 256 characters/)
+    end
+
+    it 'still rejects a denied root key that travels with a post_process' do
+      payload = { channel: { url: 'https://evil.example' }, selectors: selectors_with_gsub('x') }
+
+      expect { described_class.from_client(payload) }
+        .to raise_error(Html2rss::Web::BadRequestError, 'channel is not allowed')
+    end
+  end
 end

From e9cc90f8dbde0935e17f9de4f6e70988375498a9 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 20 Sep 2026 01:38:36 +0200
Subject: [PATCH 028/108] feat(studio): make refine one task with a live
 preview

The selector builder and synced YAML editor put the schema on the screen. Replace them with a suggested items selector, field fixes, and preview images taken from the RSS item without shipping the feed body.
---
 app/web/api/v1/preview_feed.rb               |  66 +-
 docs/design-system.md                        |   4 +-
 frontend/e2e/smoke.spec.ts                   |  37 +
 frontend/src/__tests__/ConfigStudio.test.tsx | 226 +++++-
 frontend/src/__tests__/YamlPanel.test.tsx    |  52 --
 frontend/src/__tests__/useStudio.test.ts     | 425 +++++++---
 frontend/src/api/generated/types.gen.ts      |   1 +
 frontend/src/components/ConfigStudio.tsx     | 784 ++++++++++---------
 frontend/src/components/YamlPanel.tsx        |  45 --
 frontend/src/journey/copy.ts                 |  39 +-
 frontend/src/studio/selectorDraft.ts         | 550 +++++--------
 frontend/src/studio/studioService.ts         |  84 +-
 frontend/src/studio/useStudio.ts             | 338 ++++----
 frontend/src/styles/main.css                 |  54 +-
 public/openapi.yaml                          |   3 +
 spec/html2rss/web/api/v1_spec.rb             |  28 +
 16 files changed, 1589 insertions(+), 1147 deletions(-)
 delete mode 100644 frontend/src/__tests__/YamlPanel.test.tsx
 delete mode 100644 frontend/src/components/YamlPanel.tsx

diff --git a/app/web/api/v1/preview_feed.rb b/app/web/api/v1/preview_feed.rb
index 4f1f8f4e..4c6aa201 100644
--- a/app/web/api/v1/preview_feed.rb
+++ b/app/web/api/v1/preview_feed.rb
@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require 'json'
+require 'nokogiri'
+require 'rss'
 
 module Html2rss
   module Web
@@ -97,18 +99,80 @@ def default_strategy
             end
 
             # Selected fields only. {Html2rss::Test::Result#to_h} also carries +rss+.
+            # Sample hashes omit images; those URLs are copied from the same RSS items.
             #
             # @param result [Html2rss::Test::Result]
             # @return [Hash{Symbol=>Object}]
             def preview_fields(result)
               {
                 item_count: result.item_count,
-                sample_items: result.sample_items,
+                sample_items: sample_items_with_images(result),
                 quality_report: result.quality_report&.to_h,
                 failure_kind: result.failure_kind&.to_sym,
                 validation_issues: result.validation_issues&.map(&:to_h)
               }
             end
+
+            # Same order and cap as +sample_items+. Never includes the RSS document.
+            #
+            # @param result [Html2rss::Test::Result]
+            # @return [Array<Hash>]
+            def sample_items_with_images(result)
+              items = result.sample_items
+              return items if items.empty?
+
+              urls = rss_image_urls(result.rss)
+              items.each_with_index.map do |item, index|
+                url = urls[index]
+                url ? item.merge('image' => url) : item
+              end
+            end
+
+            # @param rss [String, nil]
+            # @return [Array<String, nil>]
+            def rss_image_urls(rss)
+              return [] unless rss.is_a?(String) && !rss.strip.empty?
+
+              RSS::Parser.parse(rss, false)&.items.to_a.map { description_image_src(it) || image_enclosure_url(it) }
+            rescue RSS::Error
+              []
+            end
+
+            # First http(s) +<img src>+ in the item description. Article images are prepended there.
+            #
+            # @param item [RSS::Rss::Channel::Item]
+            # @return [String, nil]
+            def description_image_src(item)
+              html = item.description.to_s if item.respond_to?(:description)
+              return if html.nil? || html.empty?
+
+              node = Nokogiri::HTML.fragment(html).css('img').find { http_image_url(it['src']) }
+              http_image_url(node['src']) if node
+            end
+
+            # Image +enclosure+ only. Audio and other types are not preview images.
+            #
+            # @param item [RSS::Rss::Channel::Item]
+            # @return [String, nil]
+            def image_enclosure_url(item)
+              return unless item.respond_to?(:enclosure)
+
+              enclosure = item.enclosure
+              type = enclosure.respond_to?(:type) ? enclosure.type.to_s : ''
+              return unless type.downcase.start_with?('image/')
+
+              http_image_url(enclosure.url)
+            end
+
+            # @param value [String, nil]
+            # @return [String, nil]
+            def http_image_url(value)
+              url = value.to_s.strip
+              return unless url.start_with?('https://', 'http://')
+              return if url.match?(/[[:space:]"'<>]/)
+
+              url
+            end
           end
         end
       end
diff --git a/docs/design-system.md b/docs/design-system.md
index d34473a4..a193e8d5 100644
--- a/docs/design-system.md
+++ b/docs/design-system.md
@@ -42,7 +42,7 @@ If a page looks like it came from a different product, the change is wrong even
 - **Token gate:** a native `<dialog>` over the still-mounted, inert URL task (one interactive task). Auth copy is in-field (`tokenError`); ActionFeedback stays on create. Access Token persists until Logout with no storage UI.
 - **Result:** primary CTA is **Copy feed URL**. Open feed / JSON / feed-reader are demoted secondary actions and stay available while preview loads. Preview is non-blocking confirmation only. **Refine selectors** is one quiet action beside create another.
 - **Empty extraction:** **Refine selectors** is one quiet action beside Try again when the extraction is empty. It is not offered for other create errors.
-- **Refine:** `#/refine` is memory-bound. No token in the route. A missing in-memory URL recovers onto remounted `#/create`. The items selector is the task. YAML is the same config, not a second document. Primary completion is **Save and generate feed**, which returns to the result view.
+- **Refine:** `#/refine` is memory-bound. No token in the route. A missing in-memory URL recovers onto remounted `#/create`. The items selector is the task; an empty selector is filled once from suggestion, and Enhance follows that suggestion until the user changes either. Controls use one grammar: eyebrow above the control, stacked with token gaps. **Apply suggestion** is its own quiet button, not a label beside the primary. A live preview pane auto-refreshes after validation; an authenticated session may show a sample image when the preview item includes an image URL. Fix a field is limited to Title, Link, and Published date. View as YAML is read-only and demoted under the primary. When the page already publishes a feed, that notice sits above the columns. Primary completion is **Save and generate feed**, which returns to the result view. Focus is the items selector.
 - **Unmatched result:** `#/result/:token` is valid only with a matching in-memory result. Missing or mismatched tokens recover onto remounted `#/create` (no API rehydrate, no failure chrome, no durable shareable result page).
 - **Status eyebrow:** one vocabulary (`Feed ready`) on the result header; preview progress lives in the preview section.
 - **Focus:** create autofocuses the URL field; token autofocuses the token field; result focuses the Copy control; refine focuses the items selector.
@@ -55,7 +55,7 @@ If a page looks like it came from a different product, the change is wrong even
 | Output | **Feed URL** |
 | Create | **Create feed** / **Creating feed** |
 | Result | **Feed ready** / **Copy feed URL** |
-| Refine | **Refine selectors** / **Save and generate feed** |
+| Refine | **Refine selectors** / **Save and generate feed** / **View as YAML** |
 | Retry | **Try again** (button only) |
 | Preview | **Checking preview** / **Check again** |
 | Catalog | **Feed Directory** |
diff --git a/frontend/e2e/smoke.spec.ts b/frontend/e2e/smoke.spec.ts
index b02613b7..9f97e499 100644
--- a/frontend/e2e/smoke.spec.ts
+++ b/frontend/e2e/smoke.spec.ts
@@ -305,6 +305,39 @@ test.describe('frontend smoke', () => {
       });
     });
 
+    await page.route(/\/api\/v1\/feeds\/suggest_selectors$/, async (route) => {
+      await route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          success: true,
+          data: {
+            selectors: { items: { selector: 'article', enhance: false } },
+            segment_strategy: 'list',
+            admission_drops: { chrome: 0 },
+            enhance: false,
+          },
+        }),
+      });
+    });
+
+    await page.route(/\/api\/v1\/feeds\/preview$/, async (route) => {
+      await route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          success: true,
+          data: {
+            item_count: 0,
+            sample_items: [],
+            quality_report: { warnings: [], metrics: { short_title_count: 0 } },
+            failure_kind: '',
+            validation_issues: [],
+          },
+        }),
+      });
+    });
+
     await page.addInitScript(() => {
       localStorage.setItem('html2rss_access_token', 'token-123');
     });
@@ -316,6 +349,10 @@ test.describe('frontend smoke', () => {
 
     await page.getByRole('button', { name: COPY.refineSelectors }).click();
     await expect(page).toHaveURL(/\/#\/refine$/);
+    await expect(page.getByLabel(COPY.itemsSelector)).toBeVisible();
+    await expect(page.getByRole('button', { name: COPY.fieldMissing(COPY.fieldTitle) })).toBeVisible();
+    await expect(page.locator('textarea')).toHaveCount(0);
+    await expect(page.getByRole('combobox')).toHaveCount(0);
     const save = page.getByRole('button', { name: COPY.saveAndGenerate });
     await expect(save).toBeEnabled();
 
diff --git a/frontend/src/__tests__/ConfigStudio.test.tsx b/frontend/src/__tests__/ConfigStudio.test.tsx
index d3728920..76eaeb6d 100644
--- a/frontend/src/__tests__/ConfigStudio.test.tsx
+++ b/frontend/src/__tests__/ConfigStudio.test.tsx
@@ -33,42 +33,95 @@ function echoValidate() {
   );
 }
 
+function previewWithImage() {
+  return {
+    success: true,
+    data: {
+      item_count: 2,
+      sample_items: [
+        {
+          title: 'With image',
+          url: 'https://example.com/sample',
+          published_at: '2024-01-02',
+          image: 'https://cdn.example/a.jpg',
+        },
+        { title: 'No image', url: 'https://example.com/plain' },
+      ],
+      quality_report: { warnings: [], metrics: { short_title_count: 0 } },
+      failure_kind: '',
+      validation_issues: [],
+    },
+  };
+}
+
 describe('ConfigStudio', () => {
-  it('hydrates the items selector from validate and focuses it', async () => {
+  it('focuses the items selector and keeps the attribute builder hidden', async () => {
     renderStudio();
 
     const items = screen.getByLabelText(COPY.itemsSelector);
-    expect(screen.getByRole('button', { name: COPY.previewExtraction })).toBeDisabled();
+    expect(screen.getByRole('button', { name: COPY.saveAndGenerate })).toBeDisabled();
+    expect(screen.queryByRole('combobox')).not.toBeInTheDocument();
+    expect(document.querySelector('textarea')).toBeNull();
+    expect(screen.queryByText(COPY.stripHtml)).not.toBeInTheDocument();
+    expect(screen.queryByText(COPY.cleanup)).not.toBeInTheDocument();
     await waitFor(() => expect(items).toHaveFocus());
     await waitFor(() => expect(items).toHaveValue('article'));
     expect(screen.getByLabelText(COPY.enhanceItems)).toBeInTheDocument();
     expect(screen.getByRole('button', { name: COPY.applySuggestion })).toBeInTheDocument();
-    expect(screen.getByRole('button', { name: COPY.addAttribute })).toBeInTheDocument();
-    expect(screen.getByRole('button', { name: COPY.previewExtraction })).toBeEnabled();
+    expect(screen.getByRole('button', { name: COPY.fieldMissing(COPY.fieldTitle) })).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: COPY.fieldMissing(COPY.fieldLink) })).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: COPY.fieldMissing(COPY.fieldPublished) })).toBeInTheDocument();
+    expect(screen.getByText(COPY.previewFetchedCaption)).toBeInTheDocument();
+    await waitFor(() => expect(screen.getByRole('button', { name: COPY.saveAndGenerate })).toBeEnabled());
   });
 
-  it('adds an attribute, chooses an extractor, and adds then removes a post-processor', async () => {
+  it('checks enhance from suggestion and prefills an empty items selector', async () => {
     echoValidate();
-    renderStudio();
+    server.use(
+      http.post('/api/v1/feeds/suggest_selectors', () =>
+        HttpResponse.json({
+          success: true,
+          data: {
+            selectors: { items: { selector: '.post', enhance: true } },
+            segment_strategy: 'list',
+            admission_drops: { chrome: 2 },
+            enhance: true,
+          },
+        })
+      )
+    );
 
-    fireEvent.click(screen.getByRole('button', { name: COPY.addAttribute }));
-    fireEvent.input(screen.getByLabelText(COPY.attributeName), { target: { value: 'title' } });
-    fireEvent.input(screen.getByLabelText(COPY.attributeSelector), { target: { value: 'h2' } });
-    fireEvent.change(screen.getByLabelText(COPY.extractor), { target: { value: 'attribute' } });
+    renderStudio();
 
-    expect(screen.getByLabelText(COPY.htmlAttribute)).toBeInTheDocument();
+    await waitFor(() => expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('.post'));
+    expect(screen.getByLabelText(COPY.enhanceItems)).toBeChecked();
+    expect(screen.queryByText('list')).not.toBeInTheDocument();
+    expect(screen.queryByText(/chrome/)).not.toBeInTheDocument();
+    expect(screen.getByRole('button', { name: COPY.applySuggestion })).toHaveClass('btn--ghost');
+    expect(screen.getByRole('button', { name: COPY.saveAndGenerate }).closest('.ui-actions')).toBeNull();
+  });
 
-    fireEvent.click(screen.getByRole('button', { name: COPY.addPostProcessor }));
-    expect(screen.queryByLabelText(COPY.pattern)).not.toBeInTheDocument();
-    fireEvent.change(screen.getByLabelText(COPY.postProcessors), { target: { value: 'gsub' } });
-    expect(screen.getByLabelText(COPY.pattern)).toBeInTheDocument();
-    expect(screen.getByLabelText(COPY.replacement)).toBeInTheDocument();
+  it('does not overwrite a typed items selector with the suggestion', async () => {
+    echoValidate();
+    const pendingSuggestion = Promise.withResolvers<Response>();
+    server.use(http.post('/api/v1/feeds/suggest_selectors', () => pendingSuggestion.promise));
 
-    fireEvent.click(screen.getByRole('button', { name: COPY.removeNamed('gsub') }));
-    expect(screen.queryByLabelText(COPY.pattern)).not.toBeInTheDocument();
+    renderStudio();
+    fireEvent.input(screen.getByLabelText(COPY.itemsSelector), { target: { value: 'article.mine' } });
+    pendingSuggestion.resolve(
+      HttpResponse.json({
+        success: true,
+        data: {
+          selectors: { items: { selector: '.post', enhance: true } },
+          segment_strategy: 'list',
+          admission_drops: { chrome: 0 },
+          enhance: true,
+        },
+      })
+    );
 
-    fireEvent.click(screen.getByRole('button', { name: COPY.removeNamed('title') }));
-    expect(screen.queryByLabelText(COPY.attributeName)).not.toBeInTheDocument();
+    await waitFor(() => expect(screen.getByLabelText(COPY.enhanceItems)).toBeChecked());
+    expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('article.mine');
   });
 
   it('applies the capture suggestion in one click', async () => {
@@ -92,11 +145,50 @@ describe('ConfigStudio', () => {
 
     await waitFor(() => expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('.post'));
     expect(screen.getByLabelText(COPY.enhanceItems)).toBeChecked();
-    expect(screen.getByText(COPY.chromeDropped(2))).toBeInTheDocument();
-    expect(screen.getByText(/list/)).toBeInTheDocument();
+    expect(screen.queryByText(/chrome/)).not.toBeInTheDocument();
   });
 
-  it('previews sample titles after a successful check', async () => {
+  it('opens a fix-a-field panel from a hidden validation issue', async () => {
+    server.use(
+      http.post('/api/v1/feeds/validate', () =>
+        HttpResponse.json({
+          success: true,
+          data: {
+            report: {
+              success: false,
+              issues: [
+                {
+                  path: ['selectors', 'title', 'selector'],
+                  code: 'missing_key',
+                  message: 'is missing',
+                },
+                {
+                  path: ['selectors', 'url', 'selector'],
+                  code: 'constraint',
+                  message: 'is invalid',
+                },
+              ],
+            },
+            selectors: { items: { selector: 'article', enhance: false } },
+            yaml: 'selectors: {}',
+          },
+        })
+      )
+    );
+
+    renderStudio();
+
+    const summary = await screen.findByRole('button', { name: COPY.issueCount(2) });
+    expect(screen.queryByText('is missing')).not.toBeInTheDocument();
+    fireEvent.click(summary);
+
+    expect(screen.getByRole('textbox', { name: /Selector/ })).toHaveFocus();
+    expect(screen.getByText('is missing')).toBeInTheDocument();
+    expect(screen.queryByText('is invalid')).not.toBeInTheDocument();
+    expect(screen.getByRole('button', { name: COPY.issueCount(1) })).toBeInTheDocument();
+  });
+
+  it('auto-fetches a preview with url and date after validation', async () => {
     echoValidate();
     server.use(
       http.post('/api/v1/feeds/preview', () =>
@@ -104,8 +196,18 @@ describe('ConfigStudio', () => {
           success: true,
           data: {
             item_count: 1,
-            sample_items: [{ title: 'Sample headline' }],
-            quality_report: { warnings: [], metrics: { short_title_count: 0 } },
+            sample_items: [
+              {
+                title: 'Sample headline',
+                url: 'https://example.com/sample',
+                published_at: '2024-01-02',
+              },
+            ],
+            quality_report: {
+              warnings: ['native_feed_present'],
+              metrics: { short_title_count: 0 },
+              native_feed: 'https://example.com/feed.xml',
+            },
             failure_kind: '',
             validation_issues: [],
           },
@@ -114,12 +216,76 @@ describe('ConfigStudio', () => {
     );
 
     renderStudio();
-    const preview = screen.getByRole('button', { name: COPY.previewExtraction });
-    await waitFor(() => expect(preview).toBeEnabled());
-    fireEvent.click(preview);
 
-    await waitFor(() => expect(screen.getByText('Sample headline')).toBeInTheDocument());
-    expect(screen.getByText(COPY.previewItemCount(1))).toBeInTheDocument();
+    expect(screen.queryByRole('button', { name: COPY.previewChecking })).not.toBeInTheDocument();
+    await waitFor(() => expect(screen.getByText('Sample headline')).toBeInTheDocument(), { timeout: 4000 });
+    expect(screen.getByRole('link', { name: 'Sample headline' })).toHaveAttribute(
+      'href',
+      'https://example.com/sample'
+    );
+    expect(screen.getByText('https://example.com/sample')).toBeInTheDocument();
+    expect(screen.getByText('2024-01-02')).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: COPY.fieldFound(COPY.fieldTitle) })).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: COPY.fieldFound(COPY.fieldLink) })).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: COPY.fieldFound(COPY.fieldPublished) })).toBeInTheDocument();
+    expect(screen.getByText(COPY.nativeFeedTitle)).toBeInTheDocument();
+    expect(screen.getByRole('link', { name: 'https://example.com/feed.xml' })).toHaveAttribute(
+      'href',
+      'https://example.com/feed.xml'
+    );
+    expect(screen.queryByText('native_feed_present')).not.toBeInTheDocument();
+    expect(document.querySelector('img.refine-sample-image')).toBeNull();
+  });
+
+  it('renders a sample image only for an authenticated session when a url exists', async () => {
+    echoValidate();
+    server.use(http.post('/api/v1/feeds/preview', () => HttpResponse.json(previewWithImage())));
+
+    renderStudio();
+
+    await waitFor(() => expect(screen.getByText('With image')).toBeInTheDocument(), { timeout: 4000 });
+    const images = document.querySelectorAll('img.refine-sample-image');
+    expect(images).toHaveLength(1);
+    const image = images[0];
+    expect(image).toBeInstanceOf(HTMLImageElement);
+    if (!(image instanceof HTMLImageElement)) return;
+    expect(image).toHaveAttribute('src', 'https://cdn.example/a.jpg');
+    expect(image).toHaveAttribute('referrerpolicy', 'no-referrer');
+    expect(image).toHaveAttribute('loading', 'lazy');
+    expect(image).toHaveAttribute('crossorigin', 'anonymous');
+    expect(screen.getByText('No image')).toBeInTheDocument();
+  });
+
+  it('does not request a sample image without an access token', async () => {
+    echoValidate();
+    server.use(http.post('/api/v1/feeds/preview', () => HttpResponse.json(previewWithImage())));
+
+    render(<ConfigStudio url={pageUrl} token="  " onGenerate={vi.fn()} />);
+
+    await waitFor(() => expect(screen.getByText('With image')).toBeInTheDocument(), { timeout: 4000 });
+    expect(document.querySelector('img')).toBeNull();
+  });
+
+  it('offers check again when the live preview cannot be fetched', async () => {
+    echoValidate();
+    server.use(http.post('/api/v1/feeds/preview', () => HttpResponse.error()));
+
+    renderStudio();
+
+    expect(
+      await screen.findByRole('button', { name: COPY.checkAgain }, { timeout: 4000 })
+    ).toBeInTheDocument();
+    expect(screen.getByText(COPY.previewFetchedCaption)).toBeInTheDocument();
+  });
+
+  it('reveals read-only yaml without a textarea', async () => {
+    renderStudio();
+    await waitFor(() => expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('article'));
+
+    fireEvent.click(screen.getByRole('button', { name: COPY.viewAsYaml }));
+
+    expect(document.querySelector('textarea')).toBeNull();
+    await waitFor(() => expect(screen.getByText(/selector: article/)).toBeInTheDocument());
   });
 
   it('sends the validated selectors when generating a feed', async () => {
diff --git a/frontend/src/__tests__/YamlPanel.test.tsx b/frontend/src/__tests__/YamlPanel.test.tsx
deleted file mode 100644
index 3e3f1538..00000000
--- a/frontend/src/__tests__/YamlPanel.test.tsx
+++ /dev/null
@@ -1,52 +0,0 @@
-import { describe, it, expect, vi } from 'vitest';
-import { render, screen, fireEvent } from '@testing-library/preact';
-import { YamlPanel } from '../components/YamlPanel';
-import { COPY } from '../journey/copy';
-import type { StudioIssue } from '../studio/studioService';
-
-const constraintIssue: StudioIssue = {
-  path: ['selectors', 'items', 'selector'],
-  code: 'constraint',
-  message: 'is too short',
-};
-
-const parseIssue: StudioIssue = {
-  path: [],
-  code: 'parse',
-  message: 'found unexpected end',
-};
-
-describe('YamlPanel', () => {
-  it('lists validation issues as path, code, and message', () => {
-    render(
-      <YamlPanel
-        yaml="selectors: {}"
-        issues={[constraintIssue]}
-        hasSyntaxError={false}
-        onYamlInput={vi.fn()}
-      />
-    );
-
-    expect(screen.getByLabelText(COPY.yamlConfig)).toHaveValue('selectors: {}');
-    expect(screen.getByText('selectors.items.selector')).toBeInTheDocument();
-    expect(screen.getByText('constraint')).toBeInTheDocument();
-    expect(screen.getByText('is too short')).toBeInTheDocument();
-    expect(screen.queryByRole('status')).not.toBeInTheDocument();
-  });
-
-  it('shows a syntax notice when the yaml does not parse', () => {
-    render(<YamlPanel yaml="selectors: [" issues={[parseIssue]} hasSyntaxError onYamlInput={vi.fn()} />);
-
-    expect(screen.getByRole('status')).toHaveTextContent(COPY.yamlSyntax);
-    expect(screen.getByText('parse')).toBeInTheDocument();
-  });
-
-  it('forwards textarea edits', () => {
-    const onYamlInput = vi.fn<(yaml: string) => void>();
-    render(<YamlPanel yaml="" issues={[]} hasSyntaxError={false} onYamlInput={onYamlInput} />);
-
-    fireEvent.input(screen.getByLabelText(COPY.yamlConfig), { target: { value: 'selectors:\n' } });
-
-    expect(onYamlInput).toHaveBeenCalledWith('selectors:\n');
-  });
-});
diff --git a/frontend/src/__tests__/useStudio.test.ts b/frontend/src/__tests__/useStudio.test.ts
index 6643ee35..5e7b3f01 100644
--- a/frontend/src/__tests__/useStudio.test.ts
+++ b/frontend/src/__tests__/useStudio.test.ts
@@ -1,7 +1,12 @@
 import { describe, it, expect, beforeEach, afterEach, vi, type SpyInstance } from 'vitest';
 import { renderHook, act, waitFor } from '@testing-library/preact';
-import { draftFromSelectors, selectorsFromDraft } from '../studio/selectorDraft';
-import { STUDIO_VALIDATE_DELAY_MS, useStudio } from '../studio/useStudio';
+import {
+  draftFromSelectors,
+  selectorsFromDraft,
+  withFieldFixup,
+  withFieldSelector,
+} from '../studio/selectorDraft';
+import { STUDIO_PREVIEW_SETTLE_MS, STUDIO_VALIDATE_DELAY_MS, useStudio } from '../studio/useStudio';
 
 const pageUrl = 'https://example.com/articles';
 const token = 'studio-token';
@@ -19,44 +24,64 @@ function validateBody(overrides: Record<string, unknown> = {}) {
   };
 }
 
+function suggestionBody(isEnhanced = false, selector = 'article') {
+  return {
+    success: true,
+    data: {
+      selectors: { items: { selector, enhance: isEnhanced } },
+      segment_strategy: 'list',
+      admission_drops: { chrome: 2 },
+      enhance: isEnhanced,
+    },
+  };
+}
+
+function callsTo(fetchMock: SpyInstance, suffix: string) {
+  return fetchMock.mock.calls.filter((call) => String(call[0]).endsWith(suffix));
+}
+
 describe('selector draft', () => {
-  it('keeps attribute selectors, post-processors, and untouched keys', () => {
-    const draft = draftFromSelectors({
+  it('round-trips field fixups and untouched keys', () => {
+    const drafted = draftFromSelectors({
       items: { selector: 'article', enhance: true, order: 'reverse' },
-      title: {
-        selector: 'h2',
-        extractor: 'text',
-        post_process: [{ name: 'gsub', pattern: 'a', replacement: 'b' }],
-      },
       guid: ['title'],
     });
+    expect(drafted).toBeDefined();
+    if (!drafted) return;
 
-    expect(draft?.itemsSelector).toBe('article');
-    expect(draft?.enhance).toBe(true);
-    expect(draft?.itemsPreserved).toEqual({ order: 'reverse' });
-    expect(draft?.attributes[0]).toMatchObject({
-      name: 'title',
-      selector: 'h2',
-      extractor: 'text',
+    const withTitle = withFieldFixup(withFieldSelector(drafted, 'title', 'h2'), 'title', {
+      kind: 'strip_html',
     });
-    expect(draft?.attributes[0]?.postProcessors[0]).toMatchObject({
-      name: 'gsub',
-      pattern: 'a',
-      replacement: 'b',
+    const withLink = withFieldSelector(withTitle, 'link', 'a');
+    const withDate = withFieldFixup(withFieldSelector(withLink, 'published', 'time'), 'published', {
+      kind: 'trim_length',
+      length: '12',
     });
+    const withAffix = withFieldFixup(withDate, 'title', { kind: 'remove_affix', text: 'a.b' });
 
-    expect(draft).toBeDefined();
-    if (!draft) return;
-
-    expect(selectorsFromDraft(draft)).toEqual({
+    expect(withAffix.itemsPreserved).toEqual({ order: 'reverse' });
+    const wire = selectorsFromDraft(withAffix);
+    expect(wire).toEqual({
       items: { selector: 'article', enhance: true, order: 'reverse' },
       title: {
         selector: 'h2',
         extractor: 'text',
-        post_process: [{ name: 'gsub', pattern: 'a', replacement: 'b' }],
+        post_process: [{ name: 'gsub', pattern: String.raw`^(?:a\.b)|(?:a\.b)$`, replacement: '' }],
+      },
+      url: { selector: 'a', extractor: 'href' },
+      published_at: {
+        selector: 'time',
+        extractor: 'text',
+        post_process: [{ name: 'substring', start: 0, end: 11 }],
       },
       guid: ['title'],
     });
+
+    const again = draftFromSelectors(wire);
+    expect(again?.fields.title.fixup).toEqual({ kind: 'remove_affix', text: 'a.b' });
+    expect(again?.fields.published.fixup).toEqual({ kind: 'trim_length', length: '12' });
+    expect(again?.fields.link).toEqual({ selector: 'a', fixup: { kind: 'none' } });
+    expect(selectorsFromDraft(again ?? withAffix)).toEqual(wire);
   });
 });
 
@@ -75,26 +100,38 @@ describe('useStudio', () => {
 
   it('waits 300ms, sends the bearer token, and unwraps a valid report', async () => {
     vi.useFakeTimers();
-    fetchMock.mockResolvedValue(Response.json(validateBody()));
+    fetchMock.mockImplementation((input: RequestInfo | URL) => {
+      if (String(input).endsWith('/feeds/suggest_selectors')) {
+        return Promise.resolve(Response.json(suggestionBody(false)));
+      }
+      return Promise.resolve(Response.json(validateBody()));
+    });
 
     const { result } = renderHook(() => useStudio({ url: pageUrl, token }));
-    expect(fetchMock).not.toHaveBeenCalled();
+    expect(callsTo(fetchMock, '/feeds/validate')).toHaveLength(0);
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(0);
+    });
+    expect(result.current.state.draft.itemsSelector).toBe('article');
+    expect(callsTo(fetchMock, '/feeds/validate')).toHaveLength(0);
 
     await act(async () => {
       await vi.advanceTimersByTimeAsync(STUDIO_VALIDATE_DELAY_MS - 1);
     });
-    expect(fetchMock).not.toHaveBeenCalled();
+    expect(callsTo(fetchMock, '/feeds/validate')).toHaveLength(0);
 
     await act(async () => {
       await vi.advanceTimersByTimeAsync(1);
     });
 
-    expect(fetchMock).toHaveBeenCalledTimes(1);
-    expect(fetchMock.mock.calls[0]?.[0]).toBe('/api/v1/feeds/validate');
-    const init = fetchMock.mock.calls[0]?.[1];
+    const validateCalls = callsTo(fetchMock, '/feeds/validate');
+    expect(validateCalls).toHaveLength(1);
+    expect(validateCalls[0]?.[0]).toBe('/api/v1/feeds/validate');
+    const init = validateCalls[0]?.[1];
     expect(init?.headers).toMatchObject({ Authorization: `Bearer ${token}` });
     expect(JSON.parse(String(init?.body))).toEqual({
-      selectors: { items: { enhance: false } },
+      selectors: { items: { selector: 'article', enhance: false } },
     });
 
     const state = result.current.state;
@@ -103,29 +140,39 @@ describe('useStudio', () => {
     expect(state.validated).toBe(true);
     expect(state.yaml).toContain('article');
     expect(state.draft.itemsSelector).toBe('article');
+    expect(callsTo(fetchMock, '/feeds/preview')).toHaveLength(0);
   });
 
-  it('keeps returned issue codes on the invalid phase', async () => {
-    fetchMock.mockResolvedValue(
-      Response.json(
-        validateBody({
-          report: {
-            success: false,
-            issues: [
-              {
-                path: ['selectors', 'items', 'selector'],
-                code: 'missing_key',
-                message: 'is missing',
-              },
-            ],
-          },
-          selectors: { items: { enhance: false } },
-          yaml: wireNull,
-        })
-      )
-    );
+  it('keeps returned issue codes on the invalid phase and does not preview', async () => {
+    vi.useFakeTimers();
+    fetchMock.mockImplementation((input: RequestInfo | URL) => {
+      if (String(input).endsWith('/feeds/suggest_selectors')) {
+        return Promise.resolve(Response.json(suggestionBody(false)));
+      }
+      return Promise.resolve(
+        Response.json(
+          validateBody({
+            report: {
+              success: false,
+              issues: [
+                {
+                  path: ['selectors', 'items', 'selector'],
+                  code: 'missing_key',
+                  message: 'is missing',
+                },
+              ],
+            },
+            selectors: { items: { enhance: false } },
+            yaml: wireNull,
+          })
+        )
+      );
+    });
 
     const { result } = renderHook(() => useStudio({ url: pageUrl, token, validateDelayMs: 0 }));
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(0);
+    });
     await waitFor(() => expect(result.current.state.phase).toBe('invalid'));
 
     const state = result.current.state;
@@ -137,99 +184,229 @@ describe('useStudio', () => {
         message: 'is missing',
       },
     ]);
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(STUDIO_PREVIEW_SETTLE_MS);
+    });
+    expect(callsTo(fetchMock, '/feeds/preview')).toHaveLength(0);
   });
 
-  it('freezes builder hydration while yaml does not parse', async () => {
-    fetchMock.mockResolvedValueOnce(Response.json(validateBody())).mockResolvedValueOnce(
-      Response.json(
-        validateBody({
-          report: {
-            success: false,
-            issues: [
-              {
-                path: [],
-                code: 'parse',
-                message: 'could not parse',
+  it('previews only after validation succeeds and the settle delay', async () => {
+    vi.useFakeTimers();
+    fetchMock.mockImplementation((input: RequestInfo | URL) => {
+      const path = String(input);
+      if (path.endsWith('/feeds/suggest_selectors')) {
+        return Promise.resolve(Response.json(suggestionBody(false)));
+      }
+      if (path.endsWith('/feeds/preview')) {
+        return Promise.resolve(
+          Response.json({
+            success: true,
+            data: {
+              item_count: 1,
+              sample_items: [
+                { title: 'Sample', url: 'https://example.com/sample', published_at: '2024-01-02' },
+              ],
+              quality_report: {
+                warnings: [],
+                metrics: { short_title_count: 0 },
+                native_feed: 'https://example.com/feed.xml',
               },
-            ],
+              failure_kind: wireNull,
+              validation_issues: [],
+            },
+          })
+        );
+      }
+      return Promise.resolve(Response.json(validateBody()));
+    });
+
+    const { result } = renderHook(() =>
+      useStudio({ url: pageUrl, token, validateDelayMs: STUDIO_VALIDATE_DELAY_MS })
+    );
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(0);
+    });
+    expect(result.current.state.draft.itemsSelector).toBe('article');
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(STUDIO_VALIDATE_DELAY_MS);
+    });
+    expect(callsTo(fetchMock, '/feeds/preview')).toHaveLength(0);
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(STUDIO_PREVIEW_SETTLE_MS - 1);
+    });
+    expect(callsTo(fetchMock, '/feeds/preview')).toHaveLength(0);
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(1);
+    });
+
+    const state = result.current.state;
+    expect(state.live.status).toBe('ready');
+    if (state.live.status !== 'ready') return;
+    expect(state.live.sample).toEqual({
+      itemCount: 1,
+      items: [
+        {
+          title: 'Sample',
+          url: 'https://example.com/sample',
+          publishedAt: '2024-01-02',
+          imageUrl: undefined,
+        },
+      ],
+      nativeFeedUrl: 'https://example.com/feed.xml',
+      failureKind: undefined,
+    });
+    expect(callsTo(fetchMock, '/feeds/preview')).toHaveLength(1);
+  });
+
+  it('fills an empty items selector once from suggestion and does not repeat', async () => {
+    fetchMock.mockImplementation(async (input: RequestInfo | URL, init?: RequestInit) => {
+      if (String(input).endsWith('/feeds/suggest_selectors')) {
+        return Response.json(suggestionBody(true, '.post'));
+      }
+      if (String(input).endsWith('/feeds/preview')) {
+        return Response.json({
+          success: true,
+          data: {
+            item_count: 0,
+            sample_items: [],
+            quality_report: { warnings: [], metrics: { short_title_count: 0 } },
+            failure_kind: wireNull,
+            validation_issues: [],
           },
-          selectors: wireNull,
-          yaml: wireNull,
+        });
+      }
+
+      const parsed: unknown = JSON.parse(String(init?.body));
+      const selectors =
+        typeof parsed === 'object' && parsed && 'selectors' in parsed ? parsed.selectors : undefined;
+      return Response.json(
+        validateBody({
+          selectors: selectors ?? { items: { selector: '', enhance: false } },
+          yaml: 'selectors: {}\n',
         })
-      )
+      );
+    });
+
+    const { result } = renderHook(() =>
+      useStudio({ url: pageUrl, token, validateDelayMs: 0, previewSettleMs: 60_000 })
     );
 
-    const { result } = renderHook(() => useStudio({ url: pageUrl, token, validateDelayMs: 0 }));
-    await waitFor(() => {
-      expect(result.current.state.phase).toBe('editing');
-      expect(result.current.state.draft.itemsSelector).toBe('article');
+    await waitFor(() => expect(result.current.state.draft.itemsSelector).toBe('.post'));
+    expect(result.current.state.draft.enhance).toBe(true);
+    expect(callsTo(fetchMock, '/feeds/suggest_selectors')).toHaveLength(1);
+  });
+
+  it('does not overwrite an items selector the user already typed', async () => {
+    const pendingSuggestion = Promise.withResolvers<Response>();
+    fetchMock.mockImplementation((input: RequestInfo | URL, init?: RequestInit) => {
+      if (String(input).endsWith('/feeds/suggest_selectors')) {
+        return pendingSuggestion.promise;
+      }
+      if (String(input).endsWith('/feeds/preview')) {
+        return Promise.resolve(
+          Response.json({
+            success: true,
+            data: {
+              item_count: 0,
+              sample_items: [],
+              quality_report: wireNull,
+              failure_kind: wireNull,
+              validation_issues: [],
+            },
+          })
+        );
+      }
+
+      const parsed: unknown = JSON.parse(String(init?.body));
+      const selectors =
+        typeof parsed === 'object' && parsed && 'selectors' in parsed ? parsed.selectors : undefined;
+      return Promise.resolve(
+        Response.json(
+          validateBody({
+            selectors: selectors ?? { items: { selector: 'article', enhance: false } },
+          })
+        )
+      );
     });
 
+    const { result } = renderHook(() =>
+      useStudio({ url: pageUrl, token, validateDelayMs: 0, previewSettleMs: 60_000 })
+    );
+
     act(() => {
-      result.current.setYaml(':');
+      result.current.setItemsSelector('article.mine');
     });
 
-    await waitFor(() => expect(result.current.state.phase).toBe('invalid'));
-    const state = result.current.state;
-    if (state.phase !== 'invalid') return;
-    expect(state.issues[0]?.code).toBe('parse');
-    expect(state.draft.itemsSelector).toBe('article');
-    expect(state.yaml).toBe(':');
-    expect(JSON.parse(String(fetchMock.mock.calls[1]?.[1]?.body))).toEqual({ yaml: ':' });
+    await act(async () => {
+      pendingSuggestion.resolve(Response.json(suggestionBody(true, '.post')));
+    });
+
+    await waitFor(() => expect(result.current.state.draft.enhance).toBe(true));
+    expect(result.current.state.draft.itemsSelector).toBe('article.mine');
+    expect(callsTo(fetchMock, '/feeds/suggest_selectors')).toHaveLength(1);
   });
 
-  it('moves to previewed after a preview response', async () => {
+  it('keeps an http image url from the preview sample and drops anything else', async () => {
     fetchMock.mockImplementation((input: RequestInfo | URL) => {
       const path = String(input);
+      if (path.endsWith('/feeds/suggest_selectors')) {
+        return Promise.resolve(Response.json(suggestionBody(false)));
+      }
       if (path.endsWith('/feeds/preview')) {
         return Promise.resolve(
           Response.json({
             success: true,
             data: {
-              item_count: 1,
-              sample_items: [{ title: 'Sample' }],
-              quality_report: { warnings: ['short title'], metrics: { short_title_count: 1 } },
+              item_count: 2,
+              sample_items: [
+                {
+                  title: 'With image',
+                  url: 'https://example.com/a',
+                  published_at: '2024-01-02',
+                  image: 'https://cdn.example/a.jpg',
+                },
+                { title: 'Unsafe image', image: 'javascript:alert(1)' },
+              ],
+              quality_report: wireNull,
               failure_kind: wireNull,
               validation_issues: [],
             },
           })
         );
       }
-
       return Promise.resolve(Response.json(validateBody()));
     });
 
-    const { result } = renderHook(() => useStudio({ url: pageUrl, token, validateDelayMs: 0 }));
-    await waitFor(() => {
-      const state = result.current.state;
-      expect(state.phase === 'editing' && state.validated).toBe(true);
-    });
-
-    act(() => {
-      result.current.requestPreview();
-    });
+    const { result } = renderHook(() =>
+      useStudio({ url: pageUrl, token, validateDelayMs: 0, previewSettleMs: 0 })
+    );
 
-    await waitFor(() => expect(result.current.state.phase).toBe('previewed'));
-    const state = result.current.state;
-    if (state.phase !== 'previewed') return;
-    expect(state.preview).toEqual({
-      itemCount: 1,
-      titles: ['Sample'],
-      warnings: ['short title'],
-      failureKind: undefined,
-    });
+    await waitFor(() => expect(result.current.state.live.status).toBe('ready'));
+    const live = result.current.state.live;
+    if (live.status !== 'ready') return;
+    expect(live.sample.items[0]?.imageUrl).toBe('https://cdn.example/a.jpg');
+    expect(live.sample.items[1]?.imageUrl).toBeUndefined();
   });
 
   it('applies one capture suggestion onto the items selector', async () => {
     fetchMock.mockImplementation(async (input: RequestInfo | URL, init?: RequestInit) => {
       if (String(input).endsWith('/feeds/suggest_selectors')) {
+        return Response.json(suggestionBody(true, '.post'));
+      }
+      if (String(input).endsWith('/feeds/preview')) {
         return Response.json({
           success: true,
           data: {
-            selectors: { items: { selector: '.post', enhance: true } },
-            segment_strategy: 'list',
-            admission_drops: { chrome: 2 },
-            enhance: true,
+            item_count: 0,
+            sample_items: [],
+            quality_report: wireNull,
+            failure_kind: wireNull,
+            validation_issues: [],
           },
         });
       }
@@ -244,7 +421,9 @@ describe('useStudio', () => {
       );
     });
 
-    const { result } = renderHook(() => useStudio({ url: pageUrl, token, validateDelayMs: 0 }));
+    const { result } = renderHook(() =>
+      useStudio({ url: pageUrl, token, validateDelayMs: 0, previewSettleMs: 60_000 })
+    );
     await waitFor(() => expect(result.current.state.phase).toBe('editing'));
 
     act(() => {
@@ -253,29 +432,25 @@ describe('useStudio', () => {
 
     await waitFor(() => expect(result.current.state.draft.itemsSelector).toBe('.post'));
     expect(result.current.state.draft.enhance).toBe(true);
-    expect(result.current.suggestion).toEqual({
-      itemsSelector: '.post',
-      enhance: true,
-      segmentStrategy: 'list',
-      chromeDrops: 2,
-    });
   });
 
   it('fails closed when validate is unauthorized', async () => {
-    fetchMock.mockResolvedValue(
-      Response.json(
-        {
-          success: false,
-          error: {
-            code: 'UNAUTHORIZED',
-            message: 'Authentication required',
-            kind: 'auth',
-            retryable: false,
-            next_action: 'enter_token',
-            retry_action: 'none',
+    fetchMock.mockImplementation(() =>
+      Promise.resolve(
+        Response.json(
+          {
+            success: false,
+            error: {
+              code: 'UNAUTHORIZED',
+              message: 'Authentication required',
+              kind: 'auth',
+              retryable: false,
+              next_action: 'enter_token',
+              retry_action: 'none',
+            },
           },
-        },
-        { status: 401 }
+          { status: 401 }
+        )
       )
     );
 
diff --git a/frontend/src/api/generated/types.gen.ts b/frontend/src/api/generated/types.gen.ts
index b2ea3071..56ee21fc 100644
--- a/frontend/src/api/generated/types.gen.ts
+++ b/frontend/src/api/generated/types.gen.ts
@@ -290,6 +290,7 @@ export type PreviewFeedResponses = {
         warnings: Array<string>;
       } | null;
       sample_items: Array<{
+        image?: string | null;
         title: string;
       }>;
       validation_issues: Array<unknown>;
diff --git a/frontend/src/components/ConfigStudio.tsx b/frontend/src/components/ConfigStudio.tsx
index 6b2d8b03..8b452539 100644
--- a/frontend/src/components/ConfigStudio.tsx
+++ b/frontend/src/components/ConfigStudio.tsx
@@ -1,21 +1,20 @@
 import type { JSX } from 'preact';
-import { useEffect, useRef } from 'preact/hooks';
+import { useEffect, useRef, useState } from 'preact/hooks';
 import { COPY } from '../journey/copy';
 import { PreviewItem } from './PreviewItem';
-import { YamlPanel } from './YamlPanel';
+import { Notice } from './Notice';
 import {
-  EXTRACTOR_NAMES,
-  POST_PROCESSOR_NAMES,
-  type AttributeDraft,
-  type AttributePatch,
-  type ExtractorName,
-  type PostProcessorDraft,
-  type PostProcessorField,
-  type PostProcessorName,
+  issuePlace,
+  STUDIO_FIELDS,
+  hasIncompleteTrim,
+  type FieldFixup,
+  type StudioFieldId,
 } from '../studio/selectorDraft';
-import { hasSyntaxError, studioIssues, useStudio, type StudioState } from '../studio/useStudio';
+import { canSaveStudio, studioIssues, useStudio, type StudioState } from '../studio/useStudio';
+import type { StudioIssue, StudioSampleItem } from '../studio/studioService';
 
-const STUDIO_BUSY_PHASES = new Set<StudioState['phase']>(['validating', 'previewing', 'saving']);
+const FIXUP_KINDS = ['none', 'strip_html', 'trim_length', 'remove_affix'] as const;
+type FixupKind = (typeof FIXUP_KINDS)[number];
 
 interface ConfigStudioProperties {
   readonly url: string;
@@ -23,18 +22,56 @@ interface ConfigStudioProperties {
   readonly onGenerate: (selectors: Record<string, unknown>) => Promise<void>;
 }
 
+interface OpenPanel {
+  readonly field: StudioFieldId;
+  readonly focusId: string;
+  readonly nonce: number;
+}
+
 export function ConfigStudio({ url, token, onGenerate }: ConfigStudioProperties) {
   const studio = useStudio({ url, token });
-  const { state, suggestion } = studio;
-  const canPreview = (state.phase === 'editing' && state.validated) || state.phase === 'previewed';
-  const canSave = canPreview;
-  const isBusy = STUDIO_BUSY_PHASES.has(state.phase);
+  const { state } = studio;
+  const issues = studioIssues(state);
+  const [panel, setPanel] = useState<OpenPanel | undefined>(undefined);
+  const [yamlOpen, setYamlOpen] = useState(false);
+  const [copied, setCopied] = useState(false);
+  const [showUnmapped, setShowUnmapped] = useState(false);
   const itemsReference = useRef<HTMLInputElement>(null);
+  const copyResetReference = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+  const openField = panel?.field;
+  const hiddenIssues = issues.filter((issue) => isHiddenIssue(issue, openField));
+  const unmappedIssues = hiddenIssues.filter((issue) => issuePlace(issue.path).kind === 'hidden');
+  const ready = state.live.status === 'ready' ? state.live.sample : undefined;
+  const nativeFeedUrl = ready?.nativeFeedUrl;
+  const isBusy = state.phase === 'validating' || state.phase === 'saving' || state.live.status === 'loading';
 
   useEffect(() => {
     itemsReference.current?.focus();
   }, []);
 
+  useEffect(() => {
+    if (!panel) return;
+    focusElement(panel.focusId);
+  }, [panel]);
+
+  useEffect(() => {
+    return () => {
+      if (copyResetReference.current) clearTimeout(copyResetReference.current);
+    };
+  }, []);
+
+  const openFieldPanel = (field: StudioFieldId, control: 'selector' | 'fixup') => {
+    const focusId =
+      control === 'selector' ? 'studio-field-selector' : fixupControlId(state.draft.fields[field].fixup);
+    setPanel({ field, focusId, nonce: Date.now() });
+  };
+
+  const onHiddenIssues = () => {
+    const target = firstFieldIssue(hiddenIssues);
+    if (target) openFieldPanel(target.field, target.control);
+    if (unmappedIssues.length > 0) setShowUnmapped(true);
+  };
+
   return (
     <section
       class="ui-card ui-card--padded ui-card--framed"
@@ -47,419 +84,446 @@ export function ConfigStudio({ url, token, onGenerate }: ConfigStudioProperties)
           {COPY.refineSelectors}
         </h1>
 
-        <label class="field-block" htmlFor="studio-items-selector">
-          <span class="ui-eyebrow">{COPY.itemsSelector}</span>
-          <input
-            id="studio-items-selector"
-            class="input input--mono"
-            value={state.draft.itemsSelector}
-            autoFocus
-            ref={itemsReference}
-            spellcheck={false}
-            onInput={(event) => studio.setItemsSelector(inputValue(event))}
-          />
-        </label>
+        {nativeFeedUrl ? (
+          <Notice title={COPY.nativeFeedTitle}>
+            <a class="input--mono" href={nativeFeedUrl} target="_blank" rel="noopener noreferrer">
+              {nativeFeedUrl}
+            </a>
+          </Notice>
+        ) : undefined}
 
-        <label class="field-block" htmlFor="studio-enhance">
-          <span class="ui-eyebrow">{COPY.enhanceItems}</span>
-          <input
-            id="studio-enhance"
-            type="checkbox"
-            checked={state.draft.enhance}
-            onChange={(event) => studio.setEnhance(isInputChecked(event))}
-          />
-        </label>
+        {state.phase === 'failed' ? <Notice title={state.message} tone="error" /> : undefined}
 
-        <div class="ui-actions">
-          <button
-            type="button"
-            class="btn btn--primary"
-            disabled={!canSave}
-            onClick={() => {
-              void studio.save(onGenerate);
-            }}
-          >
-            {state.phase === 'saving' ? COPY.creating : COPY.saveAndGenerate}
-          </button>
-          <button type="button" class="btn btn--quiet" onClick={() => studio.requestSuggestion()}>
-            {COPY.applySuggestion}
-          </button>
-          <button
-            type="button"
-            class="btn btn--ghost"
-            disabled={!canPreview}
-            onClick={() => studio.requestPreview()}
-          >
-            {state.phase === 'previewing' ? COPY.previewChecking : COPY.previewExtraction}
-          </button>
-        </div>
+        <div class="refine-columns">
+          <div class="refine-pane layout-stack">
+            <label class="field-block" htmlFor="studio-items-selector">
+              <span class="ui-eyebrow">{COPY.itemsSelector}</span>
+              <input
+                id="studio-items-selector"
+                class="input input--mono"
+                value={state.draft.itemsSelector}
+                autoFocus
+                ref={itemsReference}
+                spellcheck={false}
+                onInput={(event) => studio.setItemsSelector(inputValue(event))}
+              />
+              <FieldErrors
+                messages={messagesFor(issues, (issue) => issuePlace(issue.path).kind === 'items')}
+              />
+            </label>
 
-        {suggestion ? (
-          <p>
-            <span class="ui-eyebrow">{COPY.suggestion}</span> <span>{suggestion.segmentStrategy}</span>{' '}
-            <span>{COPY.chromeDropped(suggestion.chromeDrops)}</span>
-          </p>
-        ) : undefined}
+            <label class="field-block" htmlFor="studio-enhance">
+              <span class="ui-eyebrow">{COPY.enhanceItems}</span>
+              <input
+                id="studio-enhance"
+                class="refine-check"
+                type="checkbox"
+                checked={state.draft.enhance}
+                onChange={(event) => studio.setEnhance(isInputChecked(event))}
+              />
+              <FieldErrors
+                messages={messagesFor(issues, (issue) => issuePlace(issue.path).kind === 'enhance')}
+              />
+            </label>
 
-        <div class="layout-stack">
-          <p class="ui-eyebrow">{COPY.attributeSelectors}</p>
-          {state.draft.attributes.map((attribute) => (
-            <AttributeEditor
-              key={attribute.id}
-              attribute={attribute}
-              isFrozen={hasSyntaxError(state)}
-              onChange={(patch) => studio.changeAttribute(attribute.id, patch)}
-              onRemove={() => studio.deleteAttribute(attribute.id)}
-              onAddProcessor={() => studio.appendPostProcessor(attribute.id)}
-              onRemoveProcessor={(processorId) => studio.deletePostProcessor(attribute.id, processorId)}
-              onRenameProcessor={(processorId, name) =>
-                studio.changePostProcessorName(attribute.id, processorId, name)
-              }
-              onProcessorField={(processorId, field, value) =>
-                studio.changePostProcessorField(attribute.id, processorId, field, value)
-              }
-            />
-          ))}
-          <button type="button" class="btn btn--quiet" onClick={() => studio.appendAttribute()}>
-            {COPY.addAttribute}
-          </button>
-        </div>
+            {hiddenIssues.length > 0 ? (
+              <button type="button" class="btn btn--quiet btn--linkish" onClick={onHiddenIssues}>
+                {COPY.issueCount(hiddenIssues.length)}
+              </button>
+            ) : undefined}
 
-        <YamlPanel
-          yaml={state.yaml}
-          issues={studioIssues(state)}
-          hasSyntaxError={hasSyntaxError(state)}
-          onYamlInput={(yaml) => studio.setYaml(yaml)}
-        />
+            {panel ? (
+              <FieldFixPanel
+                field={panel.field}
+                selector={state.draft.fields[panel.field].selector}
+                fixup={state.draft.fields[panel.field].fixup}
+                selectorMessages={fieldMessages(issues, panel.field, 'selector')}
+                fixupMessages={fieldMessages(issues, panel.field, 'fixup')}
+                onSelector={(selector) => studio.setFieldSelector(panel.field, selector)}
+                onFixup={(fixup) => studio.setFieldFixup(panel.field, fixup)}
+              />
+            ) : undefined}
+
+            {showUnmapped && unmappedIssues.length > 0 ? (
+              <Notice tone="error">
+                {unmappedIssues.map((issue) => (
+                  <p key={issueKey(issue)}>{issue.message}</p>
+                ))}
+              </Notice>
+            ) : undefined}
 
-        <PreviewReadout state={state} />
+            <button
+              type="button"
+              class="btn btn--ghost refine-action"
+              onClick={() => studio.requestSuggestion()}
+            >
+              {COPY.applySuggestion}
+            </button>
+            <button
+              type="button"
+              class="btn btn--primary refine-action"
+              disabled={!canSaveStudio(state)}
+              onClick={() => {
+                void studio.save(onGenerate);
+              }}
+            >
+              {state.phase === 'saving' ? COPY.creating : COPY.saveAndGenerate}
+            </button>
 
-        {state.phase === 'failed' ? <p role="alert">{state.message}</p> : undefined}
+            <div class="layout-stack layout-stack--tight">
+              <button
+                type="button"
+                class="btn btn--quiet btn--linkish"
+                onClick={() => setYamlOpen((open) => !open)}
+              >
+                {COPY.viewAsYaml}
+              </button>
+              {yamlOpen ? (
+                <>
+                  <pre class="refine-yaml input input--mono">{state.yaml}</pre>
+                  <button
+                    type="button"
+                    class="btn btn--quiet btn--linkish"
+                    onClick={() => {
+                      void copyYaml(state.yaml, setCopied, copyResetReference);
+                    }}
+                  >
+                    {copied ? COPY.copied : COPY.copy}
+                  </button>
+                </>
+              ) : undefined}
+            </div>
+          </div>
+
+          <PreviewPane
+            state={state}
+            token={token}
+            onOpenField={openFieldPanel}
+            onRetry={studio.retryPreview}
+          />
+        </div>
       </div>
     </section>
   );
 }
 
-interface AttributeEditorProperties {
-  readonly attribute: AttributeDraft;
-  readonly isFrozen: boolean;
-  readonly onChange: (patch: AttributePatch) => void;
-  readonly onRemove: () => void;
-  readonly onAddProcessor: () => void;
-  readonly onRemoveProcessor: (processorId: string) => void;
-  readonly onRenameProcessor: (processorId: string, name: PostProcessorName) => void;
-  readonly onProcessorField: (processorId: string, field: PostProcessorField, value: string) => void;
+function PreviewPane({
+  state,
+  token,
+  onOpenField,
+  onRetry,
+}: {
+  readonly state: StudioState;
+  readonly token: string;
+  readonly onOpenField: (field: StudioFieldId, control: 'selector' | 'fixup') => void;
+  readonly onRetry: () => void;
+}) {
+  const items = state.live.status === 'ready' ? state.live.sample.items : [];
+  const canShowImages = token.trim().length > 0;
+
+  return (
+    <div class="refine-pane layout-stack" aria-label={COPY.previewRegion}>
+      <p class="field-help">{COPY.previewFetchedCaption}</p>
+      <div class="refine-status" role="group" aria-label={COPY.previewStatus}>
+        {STUDIO_FIELDS.map((field) => {
+          const label = fieldLabel(field);
+          const isFound = hasSampleField(items, field);
+          return (
+            <button
+              key={field}
+              type="button"
+              class="btn btn--quiet btn--linkish"
+              onClick={() => onOpenField(field, 'selector')}
+            >
+              {isFound ? COPY.fieldFound(label) : COPY.fieldMissing(label)}
+            </button>
+          );
+        })}
+      </div>
+
+      {state.live.status === 'loading' ? (
+        <div class="preview-feedback preview-feedback--loading">
+          <span class="preview-feedback__spinner" aria-hidden="true" />
+          <span>{COPY.previewChecking}</span>
+        </div>
+      ) : undefined}
+
+      {state.live.status === 'failed' ? (
+        <div class="preview-feedback preview-feedback--error">
+          <span>{state.live.message}</span>
+          <button type="button" class="btn btn--quiet btn--linkish" onClick={onRetry}>
+            {COPY.checkAgain}
+          </button>
+        </div>
+      ) : undefined}
+
+      {items.length > 0 ? (
+        <ul class="ui-item-list" role="list">
+          {items.map((item, index) => (
+            <li key={sampleKey(item, index)} class="ui-item">
+              {canShowImages && item.imageUrl ? <SampleImage url={item.imageUrl} /> : undefined}
+              <PreviewItem title={item.title} url={item.url} publishedLabel={item.publishedAt} />
+              {item.url ? <p class="ui-item__meta input--mono">{item.url}</p> : undefined}
+            </li>
+          ))}
+        </ul>
+      ) : undefined}
+    </div>
+  );
 }
 
-function AttributeEditor({
-  attribute,
-  isFrozen,
-  onChange,
-  onRemove,
-  onAddProcessor,
-  onRemoveProcessor,
-  onRenameProcessor,
-  onProcessorField,
-}: AttributeEditorProperties) {
-  const nameId = `studio-attribute-name-${attribute.id}`;
-  const selectorId = `studio-attribute-selector-${attribute.id}`;
-  const extractorId = `studio-extractor-${attribute.id}`;
+function SampleImage({ url }: { readonly url: string }) {
+  const [visible, setVisible] = useState(true);
+  if (!visible) return;
 
   return (
-    <div class="layout-stack layout-section-divided">
-      <label class="field-block" htmlFor={nameId}>
-        <span class="ui-eyebrow">{COPY.attributeName}</span>
-        <input
-          id={nameId}
-          class="input"
-          value={attribute.name}
-          disabled={isFrozen}
-          onInput={(event) => onChange({ name: inputValue(event) })}
-        />
-      </label>
-      <label class="field-block" htmlFor={selectorId}>
-        <span class="ui-eyebrow">{COPY.attributeSelector}</span>
+    <img
+      class="refine-sample-image"
+      alt=""
+      src={url}
+      referrerPolicy="no-referrer"
+      loading="lazy"
+      crossOrigin="anonymous"
+      onError={() => setVisible(false)}
+    />
+  );
+}
+
+function FieldFixPanel({
+  field,
+  selector,
+  fixup,
+  selectorMessages,
+  fixupMessages,
+  onSelector,
+  onFixup,
+}: {
+  readonly field: StudioFieldId;
+  readonly selector: string;
+  readonly fixup: FieldFixup;
+  readonly selectorMessages: readonly string[];
+  readonly fixupMessages: readonly string[];
+  readonly onSelector: (selector: string) => void;
+  readonly onFixup: (fixup: FieldFixup) => void;
+}) {
+  const lengthError = hasIncompleteTrim(fixup) ? COPY.trimAtLeastTwo : undefined;
+
+  return (
+    <div id="studio-field-panel" class="layout-stack layout-stack--tight">
+      <p class="ui-eyebrow">{fieldLabel(field)}</p>
+      <label class="field-block" htmlFor="studio-field-selector">
+        <span class="ui-eyebrow">{COPY.selector}</span>
         <input
-          id={selectorId}
+          id="studio-field-selector"
           class="input input--mono"
-          value={attribute.selector}
-          disabled={isFrozen}
+          value={selector}
           spellcheck={false}
-          onInput={(event) => onChange({ selector: inputValue(event) })}
+          onInput={(event) => onSelector(inputValue(event))}
         />
+        <FieldErrors messages={selectorMessages} />
       </label>
-      <label class="field-block" htmlFor={extractorId}>
-        <span class="ui-eyebrow">{COPY.extractor}</span>
+      <label class="field-block" htmlFor="studio-cleanup">
+        <span class="ui-eyebrow">{COPY.cleanup}</span>
         <select
-          id={extractorId}
+          id="studio-cleanup"
           class="input"
-          value={attribute.extractor}
-          disabled={isFrozen}
+          value={fixup.kind}
           onChange={(event) => {
             const value = inputValue(event);
-            if (!isExtractorName(value)) return;
-            onChange({ extractor: value });
+            if (!isFixupKind(value)) return;
+            onFixup(fixupFromKind(value, fixup));
           }}
         >
-          {EXTRACTOR_NAMES.map((name) => (
-            <option key={name} value={name}>
-              {name}
-            </option>
-          ))}
+          <option value="none">{COPY.noCleanup}</option>
+          <option value="strip_html">{COPY.stripHtml}</option>
+          <option value="trim_length">{COPY.trimToLength}</option>
+          <option value="remove_affix">{COPY.removeAffix}</option>
         </select>
+        <FieldErrors messages={fixupMessages} />
       </label>
-      {attribute.extractor === 'attribute' ? (
-        <label class="field-block" htmlFor={`studio-html-attribute-${attribute.id}`}>
-          <span class="ui-eyebrow">{COPY.htmlAttribute}</span>
+      {fixup.kind === 'trim_length' ? (
+        <label class="field-block" htmlFor="studio-fixup-length">
+          <span class="ui-eyebrow">{COPY.length}</span>
           <input
-            id={`studio-html-attribute-${attribute.id}`}
+            id="studio-fixup-length"
             class="input input--mono"
-            value={attribute.attributeName}
-            disabled={isFrozen}
-            spellcheck={false}
-            onInput={(event) => onChange({ attributeName: inputValue(event) })}
+            type="number"
+            min={2}
+            inputMode="numeric"
+            value={fixup.length}
+            onInput={(event) => onFixup({ kind: 'trim_length', length: inputValue(event) })}
           />
+          <FieldErrors messages={lengthError ? [lengthError] : []} />
         </label>
       ) : undefined}
-      {attribute.extractor === 'static' ? (
-        <label class="field-block" htmlFor={`studio-static-${attribute.id}`}>
-          <span class="ui-eyebrow">{COPY.staticValue}</span>
+      {fixup.kind === 'remove_affix' ? (
+        <label class="field-block" htmlFor="studio-fixup-affix">
+          <span class="ui-eyebrow">{COPY.prefixOrSuffix}</span>
           <input
-            id={`studio-static-${attribute.id}`}
+            id="studio-fixup-affix"
             class="input"
-            value={attribute.staticValue}
-            disabled={isFrozen}
-            onInput={(event) => onChange({ staticValue: inputValue(event) })}
+            value={fixup.text}
+            onInput={(event) => onFixup({ kind: 'remove_affix', text: inputValue(event) })}
           />
         </label>
       ) : undefined}
-
-      <div class="layout-stack layout-stack--tight">
-        <p class="ui-eyebrow">{COPY.postProcessors}</p>
-        {attribute.postProcessors.map((processor) => (
-          <ProcessorEditor
-            key={processor.id}
-            processor={processor}
-            isFrozen={isFrozen}
-            onRename={(name) => onRenameProcessor(processor.id, name)}
-            onField={(field, value) => onProcessorField(processor.id, field, value)}
-            onRemove={() => onRemoveProcessor(processor.id)}
-          />
-        ))}
-        <button type="button" class="btn btn--quiet" disabled={isFrozen} onClick={onAddProcessor}>
-          {COPY.addPostProcessor}
-        </button>
-      </div>
-
-      <button
-        type="button"
-        class="btn btn--quiet btn--linkish"
-        disabled={isFrozen}
-        aria-label={COPY.removeNamed(attribute.name.trim() || COPY.attributeName)}
-        onClick={onRemove}
-      >
-        {COPY.removeAttribute}
-      </button>
     </div>
   );
 }
 
-interface ProcessorEditorProperties {
-  readonly processor: PostProcessorDraft;
-  readonly isFrozen: boolean;
-  readonly onRename: (name: PostProcessorName) => void;
-  readonly onField: (field: PostProcessorField, value: string) => void;
-  readonly onRemove: () => void;
-}
-
-function ProcessorEditor({ processor, isFrozen, onRename, onField, onRemove }: ProcessorEditorProperties) {
-  const selectId = `studio-processor-${processor.id}`;
-
+function FieldErrors({ messages }: { readonly messages: readonly string[] }) {
+  if (messages.length === 0) return;
   return (
-    <div class="layout-stack layout-stack--tight">
-      {processor.name === 'unrecognized' ? (
-        <p class="input input--mono">{processorCaption(processor)}</p>
-      ) : (
-        <label class="field-block" htmlFor={selectId}>
-          <span class="ui-eyebrow">{COPY.postProcessors}</span>
-          <select
-            id={selectId}
-            class="input"
-            value={processor.name}
-            disabled={isFrozen}
-            onChange={(event) => {
-              const value = inputValue(event);
-              if (!isPostProcessorName(value)) return;
-              onRename(value);
-            }}
-          >
-            {POST_PROCESSOR_NAMES.map((name) => (
-              <option key={name} value={name}>
-                {name}
-              </option>
-            ))}
-          </select>
-        </label>
-      )}
-      <ProcessorFields processor={processor} isFrozen={isFrozen} onField={onField} />
-      <button
-        type="button"
-        class="btn btn--quiet btn--linkish"
-        disabled={isFrozen}
-        aria-label={COPY.removeNamed(processorCaption(processor))}
-        onClick={onRemove}
-      >
-        {COPY.removeAttribute}
-      </button>
-    </div>
+    <>
+      {messages.map((message, index) => (
+        <span key={`${index}-${message}`} class="field-error">
+          {message}
+        </span>
+      ))}
+    </>
   );
 }
 
-function ProcessorFields({
-  processor,
-  isFrozen,
-  onField,
-}: {
-  readonly processor: PostProcessorDraft;
-  readonly isFrozen: boolean;
-  readonly onField: (field: PostProcessorField, value: string) => void;
-}) {
-  switch (processor.name) {
-    case 'gsub': {
-      return (
-        <>
-          <ProcessorInput
-            id={`studio-pattern-${processor.id}`}
-            label={COPY.pattern}
-            value={processor.pattern}
-            isFrozen={isFrozen}
-            onInput={(value) => onField('pattern', value)}
-          />
-          <ProcessorInput
-            id={`studio-replacement-${processor.id}`}
-            label={COPY.replacement}
-            value={processor.replacement}
-            isFrozen={isFrozen}
-            onInput={(value) => onField('replacement', value)}
-          />
-        </>
-      );
+function fieldLabel(field: StudioFieldId): string {
+  switch (field) {
+    case 'title': {
+      return COPY.fieldTitle;
     }
-    case 'substring': {
-      return (
-        <>
-          <ProcessorInput
-            id={`studio-start-${processor.id}`}
-            label={COPY.rangeStart}
-            value={processor.start}
-            isFrozen={isFrozen}
-            onInput={(value) => onField('start', value)}
-          />
-          <ProcessorInput
-            id={`studio-end-${processor.id}`}
-            label={COPY.rangeEnd}
-            value={processor.end}
-            isFrozen={isFrozen}
-            onInput={(value) => onField('end', value)}
-          />
-        </>
-      );
+    case 'link': {
+      return COPY.fieldLink;
     }
-    case 'template': {
-      return (
-        <ProcessorInput
-          id={`studio-template-${processor.id}`}
-          label={COPY.templateString}
-          value={processor.template}
-          isFrozen={isFrozen}
-          onInput={(value) => onField('template', value)}
-        />
-      );
+    case 'published': {
+      return COPY.fieldPublished;
     }
-    default: {
-      return;
+  }
+}
+
+function hasSampleField(items: readonly StudioSampleItem[], field: StudioFieldId): boolean {
+  switch (field) {
+    case 'title': {
+      return items.some((item) => item.title.trim().length > 0);
+    }
+    case 'link': {
+      return items.some((item) => item.url !== undefined);
+    }
+    case 'published': {
+      return items.some((item) => item.publishedAt !== undefined);
     }
   }
 }
 
-function ProcessorInput({
-  id,
-  label,
-  value,
-  isFrozen,
-  onInput,
-}: {
-  readonly id: string;
-  readonly label: string;
-  readonly value: string;
-  readonly isFrozen: boolean;
-  readonly onInput: (value: string) => void;
-}) {
-  return (
-    <label class="field-block" htmlFor={id}>
-      <span class="ui-eyebrow">{label}</span>
-      <input
-        id={id}
-        class="input input--mono"
-        value={value}
-        disabled={isFrozen}
-        spellcheck={false}
-        onInput={(event) => onInput(inputValue(event))}
-      />
-    </label>
-  );
+function fieldMessages(
+  issues: readonly StudioIssue[],
+  field: StudioFieldId,
+  control: 'selector' | 'fixup'
+): readonly string[] {
+  return messagesFor(issues, (issue) => {
+    const place = issuePlace(issue.path);
+    return place.kind === 'field' && place.field === field && place.control === control;
+  });
 }
 
-function PreviewReadout({ state }: { readonly state: StudioState }) {
-  if (state.phase === 'previewing') {
-    return <p class="ui-eyebrow">{COPY.previewChecking}</p>;
+function messagesFor(
+  issues: readonly StudioIssue[],
+  isMatch: (issue: StudioIssue) => boolean
+): readonly string[] {
+  const messages: string[] = [];
+  for (const issue of issues) {
+    if (isMatch(issue)) messages.push(issue.message);
   }
+  return messages;
+}
 
-  if (state.phase !== 'previewed') return;
-
-  return (
-    <div class="layout-stack layout-stack--tight" aria-label={COPY.previewRegion}>
-      <p class="ui-eyebrow">{COPY.previewItemCount(state.preview.itemCount)}</p>
-      {state.preview.titles.length > 0 ? (
-        <ul class="ui-item-list" role="list">
-          {state.preview.titles.map((title, index) => (
-            <li key={`${title}-${index}`} class="ui-item">
-              <PreviewItem title={title} />
-            </li>
-          ))}
-        </ul>
-      ) : undefined}
-      {state.preview.warnings.map((warning) => (
-        <p key={warning}>{warning}</p>
-      ))}
-    </div>
-  );
+function isHiddenIssue(issue: StudioIssue, openField: StudioFieldId | undefined): boolean {
+  const place = issuePlace(issue.path);
+  if (place.kind === 'items' || place.kind === 'enhance') return false;
+  if (place.kind === 'field') return place.field !== openField;
+  return true;
 }
 
-function inputValue(event: JSX.TargetedEvent<HTMLInputElement | HTMLSelectElement>): string {
-  return event.currentTarget.value;
+function firstFieldIssue(
+  issues: readonly StudioIssue[]
+): { readonly field: StudioFieldId; readonly control: 'selector' | 'fixup' } | undefined {
+  for (const issue of issues) {
+    const place = issuePlace(issue.path);
+    if (place.kind === 'field') return { field: place.field, control: place.control };
+  }
+  return undefined;
 }
 
-function isInputChecked(event: JSX.TargetedEvent<HTMLInputElement>): boolean {
-  return event.currentTarget.checked;
+function fixupControlId(fixup: FieldFixup): string {
+  switch (fixup.kind) {
+    case 'trim_length': {
+      return 'studio-fixup-length';
+    }
+    case 'remove_affix': {
+      return 'studio-fixup-affix';
+    }
+    case 'none':
+    case 'strip_html': {
+      return 'studio-cleanup';
+    }
+  }
 }
 
-function isExtractorName(value: string): value is ExtractorName {
-  for (const name of EXTRACTOR_NAMES) {
-    if (name === value) return true;
+function fixupFromKind(kind: FixupKind, current: FieldFixup): FieldFixup {
+  switch (kind) {
+    case 'none': {
+      return { kind: 'none' };
+    }
+    case 'strip_html': {
+      return { kind: 'strip_html' };
+    }
+    case 'trim_length': {
+      return { kind: 'trim_length', length: current.kind === 'trim_length' ? current.length : '' };
+    }
+    case 'remove_affix': {
+      return { kind: 'remove_affix', text: current.kind === 'remove_affix' ? current.text : '' };
+    }
   }
-  return false;
 }
 
-function isPostProcessorName(value: string): value is PostProcessorName {
-  for (const name of POST_PROCESSOR_NAMES) {
-    if (name === value) return true;
+function isFixupKind(value: string): value is FixupKind {
+  for (const kind of FIXUP_KINDS) {
+    if (kind === value) return true;
   }
   return false;
 }
 
-function processorCaption(processor: PostProcessorDraft): string {
-  if (processor.name !== 'unrecognized') return processor.name;
-  const rawName = processor.raw.name;
-  return typeof rawName === 'string' ? rawName : processor.name;
+function sampleKey(item: StudioSampleItem, index: number): string {
+  return `${item.title}-${item.url ?? ''}-${item.publishedAt ?? ''}-${index}`;
+}
+
+function issueKey(issue: StudioIssue): string {
+  return `${issue.path.join('.')}:${issue.code}:${issue.message}`;
+}
+
+function focusElement(id: string) {
+  const element = document.querySelector(`#${id}`);
+  if (!(element instanceof HTMLElement)) return;
+  element.focus();
+  if (typeof element.scrollIntoView === 'function') element.scrollIntoView();
+}
+
+function inputValue(event: JSX.TargetedEvent<HTMLInputElement | HTMLSelectElement>): string {
+  return event.currentTarget.value;
+}
+
+function isInputChecked(event: JSX.TargetedEvent<HTMLInputElement>): boolean {
+  return event.currentTarget.checked;
+}
+
+async function copyYaml(
+  yaml: string,
+  setCopied: (isCopied: boolean) => void,
+  resetReference: { current: ReturnType<typeof setTimeout> | undefined }
+) {
+  try {
+    await navigator.clipboard.writeText(yaml);
+    setCopied(true);
+    if (resetReference.current) clearTimeout(resetReference.current);
+    resetReference.current = setTimeout(() => setCopied(false), 2500);
+  } catch {
+    // Clipboard may be unavailable in restricted contexts.
+  }
 }
diff --git a/frontend/src/components/YamlPanel.tsx b/frontend/src/components/YamlPanel.tsx
deleted file mode 100644
index 4e0eadcf..00000000
--- a/frontend/src/components/YamlPanel.tsx
+++ /dev/null
@@ -1,45 +0,0 @@
-import type { JSX } from 'preact';
-import { COPY } from '../journey/copy';
-import type { StudioIssue } from '../studio/studioService';
-
-interface YamlPanelProperties {
-  readonly yaml: string;
-  readonly issues: readonly StudioIssue[];
-  readonly hasSyntaxError: boolean;
-  readonly onYamlInput: (yaml: string) => void;
-}
-
-export function YamlPanel({ yaml, issues, hasSyntaxError, onYamlInput }: YamlPanelProperties) {
-  return (
-    <div class="layout-stack">
-      <label class="field-block" htmlFor="studio-yaml">
-        <span class="ui-eyebrow">{COPY.yamlConfig}</span>
-        <textarea
-          id="studio-yaml"
-          class="input input--mono studio-yaml"
-          value={yaml}
-          spellcheck={false}
-          onInput={(event) => onYamlInput(textareaValue(event))}
-        />
-      </label>
-      {hasSyntaxError ? <p role="status">{COPY.yamlSyntax}</p> : undefined}
-      {issues.length > 0 ? (
-        <ul>
-          {issues.map((issue) => (
-            <li key={issueKey(issue)}>
-              <span>{issue.path.join('.')}</span> <span>{issue.code}</span> <span>{issue.message}</span>
-            </li>
-          ))}
-        </ul>
-      ) : undefined}
-    </div>
-  );
-}
-
-function textareaValue(event: JSX.TargetedEvent<HTMLTextAreaElement>): string {
-  return event.currentTarget.value;
-}
-
-function issueKey(issue: StudioIssue): string {
-  return `${issue.path.join('.')}:${issue.code}:${issue.message}`;
-}
diff --git a/frontend/src/journey/copy.ts b/frontend/src/journey/copy.ts
index 346a5ac8..e9d43ef0 100644
--- a/frontend/src/journey/copy.ts
+++ b/frontend/src/journey/copy.ts
@@ -71,26 +71,23 @@ export const COPY = {
   itemsSelector: 'Items selector',
   enhanceItems: 'Enhance items',
   applySuggestion: 'Apply suggestion',
-  suggestion: 'Suggestion',
-  chromeDropped: (count: number) => `${count} chrome dropped`,
-  attributeSelectors: 'Attributes',
-  attributeName: 'Name',
-  attributeSelector: 'Selector',
-  extractor: 'Extractor',
-  htmlAttribute: 'HTML attribute',
-  staticValue: 'Static value',
-  addAttribute: 'Add attribute',
-  removeAttribute: 'Remove',
-  removeNamed: (name: string) => `Remove ${name}`,
-  postProcessors: 'Post-processors',
-  addPostProcessor: 'Add post-processor',
-  previewExtraction: 'Preview',
   saveAndGenerate: 'Save and generate feed',
-  yamlConfig: 'YAML',
-  yamlSyntax: 'YAML could not be parsed.',
-  pattern: 'Pattern',
-  replacement: 'Replacement',
-  rangeStart: 'Start',
-  rangeEnd: 'End',
-  templateString: 'Template',
+  viewAsYaml: 'View as YAML',
+  previewFetchedCaption: 'Based on the page as fetched just now',
+  nativeFeedTitle: 'This site already publishes a feed.',
+  fieldTitle: 'Title',
+  fieldLink: 'Link',
+  fieldPublished: 'Published date',
+  fieldFound: (name: string) => `${name} — found`,
+  fieldMissing: (name: string) => `${name} — not found`,
+  selector: 'Selector',
+  cleanup: 'Cleanup',
+  noCleanup: 'None',
+  stripHtml: 'Strip HTML',
+  trimToLength: 'Trim to length',
+  removeAffix: 'Remove a fixed prefix or suffix',
+  length: 'Length',
+  prefixOrSuffix: 'Prefix or suffix',
+  trimAtLeastTwo: 'Enter 2 or more.',
+  issueCount: (count: number) => (count === 1 ? '1 issue' : `${count} issues`),
 } as const;
diff --git a/frontend/src/studio/selectorDraft.ts b/frontend/src/studio/selectorDraft.ts
index 25c741c7..1d59457d 100644
--- a/frontend/src/studio/selectorDraft.ts
+++ b/frontend/src/studio/selectorDraft.ts
@@ -1,65 +1,44 @@
 /**
- * Visual-builder draft for an allowlisted selectors document.
+ * Closed refine draft for the allowlisted selectors document.
  *
- * The generated client types `selectors.items` only, because the published
- * examples collapse `patternProperties`. This module owns the gem selector
- * document the builder edits. It is not a second copy of the issue schema.
+ * The screen edits an items selector, enhance, and three fields. Optional
+ * fixups become gem post-processors here; that vocabulary does not leave
+ * this module. Unknown selector keys stay in `preserved` so a validate echo
+ * does not drop them.
  */
 
-function closed<const T extends readonly string[]>(values: T): T {
-  return values;
-}
-
-export const EXTRACTOR_NAMES = closed(['text', 'attribute', 'href', 'html', 'static']);
-export type ExtractorName = (typeof EXTRACTOR_NAMES)[number];
-
-export const POST_PROCESSOR_NAMES = closed([
-  'gsub',
-  'markdown_to_html',
-  'parse_time',
-  'parse_uri',
-  'sanitize_html',
-  'substring',
-  'template',
-]);
-export type PostProcessorName = (typeof POST_PROCESSOR_NAMES)[number];
-
-export type PostProcessorDraft =
-  | { readonly id: string; readonly name: 'gsub'; readonly pattern: string; readonly replacement: string }
-  | { readonly id: string; readonly name: 'substring'; readonly start: string; readonly end: string }
-  | { readonly id: string; readonly name: 'template'; readonly template: string }
-  | {
-      readonly id: string;
-      readonly name: 'markdown_to_html' | 'parse_time' | 'parse_uri' | 'sanitize_html';
-    }
-  | { readonly id: string; readonly name: 'unrecognized'; readonly raw: Readonly<Record<string, unknown>> };
+export const STUDIO_FIELDS = ['title', 'link', 'published'] as const;
+export type StudioFieldId = (typeof STUDIO_FIELDS)[number];
+
+export type FieldFixup =
+  | { readonly kind: 'none' }
+  | { readonly kind: 'strip_html' }
+  | { readonly kind: 'trim_length'; readonly length: string }
+  | { readonly kind: 'remove_affix'; readonly text: string };
 
-export interface AttributeDraft {
-  readonly id: string;
-  readonly name: string;
+export interface FieldDraft {
   readonly selector: string;
-  readonly extractor: ExtractorName;
-  readonly attributeName: string;
-  readonly staticValue: string;
-  readonly postProcessors: readonly PostProcessorDraft[];
-  readonly preserved: Readonly<Record<string, unknown>>;
+  readonly fixup: FieldFixup;
 }
 
 export interface StudioDraft {
   readonly itemsSelector: string;
   readonly enhance: boolean;
-  readonly attributes: readonly AttributeDraft[];
+  readonly fields: Readonly<Record<StudioFieldId, FieldDraft>>;
   readonly preserved: Readonly<Record<string, unknown>>;
   readonly itemsPreserved: Readonly<Record<string, unknown>>;
 }
 
-export interface AttributePatch {
-  readonly name?: string;
-  readonly selector?: string;
-  readonly extractor?: ExtractorName;
-  readonly attributeName?: string;
-  readonly staticValue?: string;
-}
+export type IssuePlace =
+  | { readonly kind: 'items' }
+  | { readonly kind: 'enhance' }
+  | { readonly kind: 'field'; readonly field: StudioFieldId; readonly control: 'selector' | 'fixup' }
+  | { readonly kind: 'hidden' };
+
+const STRIP_HTML_PATTERN = '<[^>]*>';
+const AFFIX_PREFIX = '^(?:';
+const AFFIX_MARKER = ')|(?:';
+const AFFIX_SUFFIX = ')$';
 
 export function isPlainRecord(value: unknown): value is Record<string, unknown> {
   return (
@@ -67,35 +46,29 @@ export function isPlainRecord(value: unknown): value is Record<string, unknown>
   );
 }
 
-const mintDraftId = (() => {
-  let nextDraftId = 0;
-  return (prefix: string): string => {
-    nextDraftId += 1;
-    return `${prefix}-${nextDraftId}`;
-  };
-})();
-
 export function emptyDraft(): StudioDraft {
   return {
     itemsSelector: '',
     enhance: false,
-    attributes: [],
+    fields: {
+      title: blankField(),
+      link: blankField(),
+      published: blankField(),
+    },
     preserved: {},
     itemsPreserved: {},
   };
 }
 
 export function selectorsFromDraft(draft: StudioDraft): Record<string, unknown> {
-  const names = draft.attributes.map((attribute) => attribute.name.trim()).filter((name) => name.length > 0);
-  const selectors = withoutKeys(draft.preserved, ['items', ...names]);
+  const selectors = withoutKeys(draft.preserved, ['items', 'title', 'url', 'published_at']);
   const items: Record<string, unknown> = { ...draft.itemsPreserved, enhance: draft.enhance };
   if (draft.itemsSelector.length > 0) items.selector = draft.itemsSelector;
   selectors.items = items;
 
-  for (const attribute of draft.attributes) {
-    const name = attribute.name.trim();
-    if (!name) continue;
-    selectors[name] = attributeToWire(attribute);
+  for (const field of STUDIO_FIELDS) {
+    const wire = fieldToWire(draft.fields[field], field);
+    if (wire) selectors[wireKey(field)] = wire;
   }
 
   return selectors;
@@ -105,14 +78,14 @@ export function draftFromSelectors(value: unknown): StudioDraft | undefined {
   if (!isPlainRecord(value)) return;
 
   const items = isPlainRecord(value.items) ? value.items : undefined;
-  const attributes: AttributeDraft[] = [];
+  const fields = emptyFields();
   const preserved: Record<string, unknown> = {};
 
   for (const [key, nested] of Object.entries(value)) {
     if (key === 'items') continue;
-    const attribute = parseAttribute(key, nested);
-    if (attribute) {
-      attributes.push(attribute);
+    const parsed = parseField(key, nested);
+    if (parsed) {
+      fields[parsed.field] = parsed.draft;
     } else {
       preserved[key] = nested;
     }
@@ -121,7 +94,7 @@ export function draftFromSelectors(value: unknown): StudioDraft | undefined {
   return {
     itemsSelector: typeof items?.selector === 'string' ? items.selector : '',
     enhance: items?.enhance === true,
-    attributes,
+    fields,
     preserved,
     itemsPreserved: items ? withoutKeys(items, ['selector', 'enhance']) : {},
   };
@@ -135,93 +108,12 @@ export function withEnhance(draft: StudioDraft, isEnhanced: boolean): StudioDraf
   return { ...draft, enhance: isEnhanced };
 }
 
-export function addAttribute(draft: StudioDraft): StudioDraft {
-  return { ...draft, attributes: [...draft.attributes, blankAttribute()] };
-}
-
-export function updateAttribute(draft: StudioDraft, attributeId: string, patch: AttributePatch): StudioDraft {
-  return mapAttributes(draft, (attribute) => {
-    if (attribute.id !== attributeId) return attribute;
-    return {
-      ...attribute,
-      name: patch.name ?? attribute.name,
-      selector: patch.selector ?? attribute.selector,
-      extractor: patch.extractor ?? attribute.extractor,
-      attributeName: patch.attributeName ?? attribute.attributeName,
-      staticValue: patch.staticValue ?? attribute.staticValue,
-    };
-  });
-}
-
-export function removeAttribute(draft: StudioDraft, attributeId: string): StudioDraft {
-  return {
-    ...draft,
-    attributes: draft.attributes.filter((attribute) => attribute.id !== attributeId),
-  };
+export function withFieldSelector(draft: StudioDraft, field: StudioFieldId, selector: string): StudioDraft {
+  return mapField(draft, field, (current) => ({ ...current, selector }));
 }
 
-export function addPostProcessor(draft: StudioDraft, attributeId: string): StudioDraft {
-  return mapAttributes(draft, (attribute) => {
-    if (attribute.id !== attributeId) return attribute;
-    return {
-      ...attribute,
-      postProcessors: [
-        ...attribute.postProcessors,
-        blankProcessor('sanitize_html', mintDraftId('processor')),
-      ],
-    };
-  });
-}
-
-export function removePostProcessor(
-  draft: StudioDraft,
-  attributeId: string,
-  processorId: string
-): StudioDraft {
-  return mapAttributes(draft, (attribute) => {
-    if (attribute.id !== attributeId) return attribute;
-    return {
-      ...attribute,
-      postProcessors: attribute.postProcessors.filter((processor) => processor.id !== processorId),
-    };
-  });
-}
-
-export function renamePostProcessor(
-  draft: StudioDraft,
-  attributeId: string,
-  processorId: string,
-  name: PostProcessorName
-): StudioDraft {
-  return mapAttributes(draft, (attribute) => {
-    if (attribute.id !== attributeId) return attribute;
-    return {
-      ...attribute,
-      postProcessors: attribute.postProcessors.map((processor) =>
-        processor.id === processorId ? blankProcessor(name, processor.id) : processor
-      ),
-    };
-  });
-}
-
-export type PostProcessorField = 'pattern' | 'replacement' | 'start' | 'end' | 'template';
-
-export function updatePostProcessorField(
-  draft: StudioDraft,
-  attributeId: string,
-  processorId: string,
-  field: PostProcessorField,
-  value: string
-): StudioDraft {
-  return mapAttributes(draft, (attribute) => {
-    if (attribute.id !== attributeId) return attribute;
-    return {
-      ...attribute,
-      postProcessors: attribute.postProcessors.map((processor) =>
-        processor.id === processorId ? applyProcessorField(processor, field, value) : processor
-      ),
-    };
-  });
+export function withFieldFixup(draft: StudioDraft, field: StudioFieldId, fixup: FieldFixup): StudioDraft {
+  return mapField(draft, field, (current) => ({ ...current, fixup }));
 }
 
 export function applyItemsSuggestion(
@@ -232,226 +124,226 @@ export function applyItemsSuggestion(
   return { ...draft, itemsSelector, enhance: isEnhanced };
 }
 
-export function reuseDraftIds(
-  previous: StudioDraft,
-  incoming: StudioDraft,
-  shouldKeepBlankAttributes: boolean
-): StudioDraft {
-  const previousByName = new Map(previous.attributes.map((attribute) => [attribute.name, attribute]));
-  const attributes = incoming.attributes.map((attribute) =>
-    reuseAttributeId(attribute, previousByName.get(attribute.name))
-  );
-  const blanks = shouldKeepBlankAttributes
-    ? previous.attributes.filter((attribute) => attribute.name.trim() === '')
-    : [];
-
-  return { ...incoming, attributes: [...attributes, ...blanks] };
-}
+export function issuePlace(path: readonly string[]): IssuePlace {
+  const scope = selectorScope(path);
+  const head = scope[0];
+  if (head === 'items') {
+    return scope.includes('enhance') ? { kind: 'enhance' } : { kind: 'items' };
+  }
 
-function reuseAttributeId(attribute: AttributeDraft, prior: AttributeDraft | undefined): AttributeDraft {
-  if (!prior) return attribute;
+  const field = typeof head === 'string' ? fieldFromWireKey(head) : undefined;
+  if (!field) return { kind: 'hidden' };
   return {
-    ...attribute,
-    id: prior.id,
-    postProcessors: attribute.postProcessors.map((processor, index) =>
-      withProcessorId(processor, prior.postProcessors[index]?.id ?? processor.id)
-    ),
+    kind: 'field',
+    field,
+    control: scope.includes('post_process') ? 'fixup' : 'selector',
   };
 }
 
-function withProcessorId(processor: PostProcessorDraft, id: string): PostProcessorDraft {
-  switch (processor.name) {
-    case 'gsub':
-    case 'substring':
-    case 'template':
-    case 'markdown_to_html':
-    case 'parse_time':
-    case 'parse_uri':
-    case 'sanitize_html':
-    case 'unrecognized': {
-      return { ...processor, id };
-    }
-  }
-}
-
-function applyProcessorField(
-  processor: PostProcessorDraft,
-  field: PostProcessorField,
-  value: string
-): PostProcessorDraft {
-  switch (processor.name) {
-    case 'gsub': {
-      if (field === 'pattern') return { ...processor, pattern: value };
-      if (field === 'replacement') return { ...processor, replacement: value };
-      return processor;
-    }
-    case 'substring': {
-      if (field === 'start') return { ...processor, start: value };
-      if (field === 'end') return { ...processor, end: value };
-      return processor;
-    }
-    case 'template': {
-      if (field === 'template') return { ...processor, template: value };
-      return processor;
-    }
-    default: {
-      return processor;
-    }
-  }
+export function hasIncompleteTrim(fixup: FieldFixup): boolean {
+  if (fixup.kind !== 'trim_length' || fixup.length.trim().length === 0) return false;
+  return trimEnd(fixup.length) === undefined;
 }
 
-function blankAttribute(): AttributeDraft {
+function emptyFields(): Record<StudioFieldId, FieldDraft> {
   return {
-    id: mintDraftId('attribute'),
-    name: '',
-    selector: '',
-    extractor: 'text',
-    attributeName: '',
-    staticValue: '',
-    postProcessors: [],
-    preserved: {},
+    title: blankField(),
+    link: blankField(),
+    published: blankField(),
   };
 }
 
-function blankProcessor(name: PostProcessorName, id: string): PostProcessorDraft {
-  switch (name) {
-    case 'gsub': {
-      return { id, name, pattern: '', replacement: '' };
-    }
-    case 'substring': {
-      return { id, name, start: '', end: '' };
-    }
-    case 'template': {
-      return { id, name, template: '' };
-    }
-    case 'markdown_to_html':
-    case 'parse_time':
-    case 'parse_uri':
-    case 'sanitize_html': {
-      return { id, name };
-    }
-  }
+function blankField(): FieldDraft {
+  return { selector: '', fixup: { kind: 'none' } };
 }
 
-function mapAttributes(
+function mapField(
   draft: StudioDraft,
-  update: (attribute: AttributeDraft) => AttributeDraft
+  field: StudioFieldId,
+  update: (current: FieldDraft) => FieldDraft
 ): StudioDraft {
-  return { ...draft, attributes: draft.attributes.map((attribute) => update(attribute)) };
+  return {
+    ...draft,
+    fields: {
+      ...draft.fields,
+      [field]: update(draft.fields[field]),
+    },
+  };
 }
 
-function attributeToWire(attribute: AttributeDraft): Record<string, unknown> {
+function fieldToWire(field: FieldDraft, id: StudioFieldId): Record<string, unknown> | undefined {
+  if (field.selector.length === 0) return;
   const wire: Record<string, unknown> = {
-    ...attribute.preserved,
-    selector: attribute.selector,
-    extractor: attribute.extractor,
+    selector: field.selector,
+    extractor: extractorFor(id),
   };
-  if (attribute.extractor === 'attribute') {
-    wire.attribute = attribute.attributeName;
-  } else if (attribute.extractor === 'static') {
-    wire.static = attribute.staticValue;
-  }
-  if (attribute.postProcessors.length > 0) {
-    wire.post_process = attribute.postProcessors.map((processor) => processorToWire(processor));
-  }
+  const processor = fixupToWire(field.fixup);
+  if (processor) wire.post_process = [processor];
   return wire;
 }
 
-function processorToWire(processor: PostProcessorDraft): Record<string, unknown> {
-  switch (processor.name) {
-    case 'gsub': {
-      return { name: 'gsub', pattern: processor.pattern, replacement: processor.replacement };
-    }
-    case 'substring': {
-      const wire: Record<string, unknown> = { name: 'substring' };
-      const start = integerField(processor.start);
-      if (start !== undefined) wire.start = start;
-      const end = integerField(processor.end);
-      if (end !== undefined) wire.end = end;
-      return wire;
+function fixupToWire(fixup: FieldFixup): Record<string, unknown> | undefined {
+  switch (fixup.kind) {
+    case 'none': {
+      return;
     }
-    case 'template': {
-      return { name: 'template', string: processor.template };
+    case 'strip_html': {
+      return { name: 'gsub', pattern: STRIP_HTML_PATTERN, replacement: '' };
     }
-    case 'markdown_to_html':
-    case 'parse_time':
-    case 'parse_uri':
-    case 'sanitize_html': {
-      return { name: processor.name };
+    case 'trim_length': {
+      const end = trimEnd(fixup.length);
+      if (end === undefined) return;
+      return { name: 'substring', start: 0, end };
     }
-    case 'unrecognized': {
-      return { ...processor.raw };
+    case 'remove_affix': {
+      if (fixup.text.length === 0) return;
+      return { name: 'gsub', pattern: affixPattern(fixup.text), replacement: '' };
     }
   }
 }
 
-function parseAttribute(name: string, value: unknown): AttributeDraft | undefined {
-  if (!isPlainRecord(value)) return;
-  const extractor = knownExtractor(value.extractor);
-  if (value.extractor !== undefined && !extractor) return;
-  if (value.post_process !== undefined && !Array.isArray(value.post_process)) return;
-
-  const postProcessors: PostProcessorDraft[] = [];
-  if (Array.isArray(value.post_process)) {
-    for (const item of value.post_process) {
-      const processor = parseProcessor(item);
-      if (!processor) return;
-      postProcessors.push(processor);
-    }
-  }
+function parseField(
+  key: string,
+  value: unknown
+): { readonly field: StudioFieldId; readonly draft: FieldDraft } | undefined {
+  const field = fieldFromWireKey(key);
+  if (!field || !isPlainRecord(value) || hasForeignKeys(value)) return;
+
+  const extractor = value.extractor;
+  if (extractor !== undefined && extractor !== extractorFor(field)) return;
+
+  const fixup = parseFixup(value.post_process);
+  if (!fixup) return;
 
   return {
-    id: mintDraftId('attribute'),
-    name,
-    selector: typeof value.selector === 'string' ? value.selector : '',
-    extractor: extractor ?? 'text',
-    attributeName: typeof value.attribute === 'string' ? value.attribute : '',
-    staticValue: typeof value.static === 'string' ? value.static : '',
-    postProcessors,
-    preserved: withoutKeys(value, ['selector', 'extractor', 'attribute', 'static', 'post_process']),
+    field,
+    draft: {
+      selector: typeof value.selector === 'string' ? value.selector : '',
+      fixup,
+    },
   };
 }
 
-function parseProcessor(value: unknown): PostProcessorDraft | undefined {
+function hasForeignKeys(value: Readonly<Record<string, unknown>>): boolean {
+  for (const key of Object.keys(value)) {
+    if (key !== 'selector' && key !== 'extractor' && key !== 'post_process') return true;
+  }
+  return false;
+}
+
+function parseFixup(value: unknown): FieldFixup | undefined {
+  if (value === undefined) return { kind: 'none' };
+  if (!Array.isArray(value) || value.length !== 1) return;
+  return parseProcessor(value[0]);
+}
+
+function parseProcessor(value: unknown): FieldFixup | undefined {
   if (!isPlainRecord(value) || typeof value.name !== 'string') return;
-  const id = mintDraftId('processor');
+
   switch (value.name) {
     case 'gsub': {
-      if (typeof value.pattern !== 'string' || typeof value.replacement !== 'string') {
-        return { id, name: 'unrecognized', raw: { ...value } };
-      }
-      return { id, name: 'gsub', pattern: value.pattern, replacement: value.replacement };
+      if (typeof value.pattern !== 'string' || typeof value.replacement !== 'string') return;
+      return parseGsub(value.pattern, value.replacement);
     }
     case 'substring': {
-      return {
-        id,
-        name: 'substring',
-        start: integerText(value.start),
-        end: integerText(value.end),
-      };
+      return parseTrim(value.start, value.end);
+    }
+    default: {
+      return;
+    }
+  }
+}
+
+function parseGsub(pattern: string, replacement: string): FieldFixup | undefined {
+  if (replacement !== '') return;
+  if (pattern === STRIP_HTML_PATTERN) return { kind: 'strip_html' };
+  const text = affixText(pattern);
+  if (text === undefined || affixPattern(text) !== pattern) return;
+  return { kind: 'remove_affix', text };
+}
+
+function parseTrim(start: unknown, end: unknown): FieldFixup | undefined {
+  if (start !== 0 || typeof end !== 'number' || !Number.isSafeInteger(end) || end < 1) return;
+  return { kind: 'trim_length', length: String(end + 1) };
+}
+
+function wireKey(field: StudioFieldId): 'title' | 'url' | 'published_at' {
+  switch (field) {
+    case 'title': {
+      return 'title';
+    }
+    case 'link': {
+      return 'url';
+    }
+    case 'published': {
+      return 'published_at';
     }
-    case 'template': {
-      if (typeof value.string !== 'string') return { id, name: 'unrecognized', raw: { ...value } };
-      return { id, name: 'template', template: value.string };
+  }
+}
+
+function fieldFromWireKey(key: string): StudioFieldId | undefined {
+  switch (key) {
+    case 'title': {
+      return 'title';
     }
-    case 'markdown_to_html':
-    case 'parse_time':
-    case 'parse_uri':
-    case 'sanitize_html': {
-      return { id, name: value.name };
+    case 'url': {
+      return 'link';
+    }
+    case 'published_at': {
+      return 'published';
     }
     default: {
-      return { id, name: 'unrecognized', raw: { ...value } };
+      return undefined;
     }
   }
 }
 
-function knownExtractor(value: unknown): ExtractorName | undefined {
-  if (typeof value !== 'string') return;
-  for (const name of EXTRACTOR_NAMES) {
-    if (name === value) return name;
+function extractorFor(field: StudioFieldId): 'text' | 'href' {
+  switch (field) {
+    case 'link': {
+      return 'href';
+    }
+    case 'title':
+    case 'published': {
+      return 'text';
+    }
   }
-  return;
+}
+
+function selectorScope(path: readonly string[]): readonly string[] {
+  const index = path.indexOf('selectors');
+  return index === -1 ? path : path.slice(index + 1);
+}
+
+function trimEnd(length: string): number | undefined {
+  if (!/^\d+$/.test(length)) return;
+  const parsed = Number(length);
+  if (!Number.isSafeInteger(parsed) || parsed < 2) return;
+  return parsed - 1;
+}
+
+function affixPattern(text: string): string {
+  const escaped = escapeRegexp(text);
+  return `${AFFIX_PREFIX}${escaped}${AFFIX_MARKER}${escaped}${AFFIX_SUFFIX}`;
+}
+
+function affixText(pattern: string): string | undefined {
+  if (!pattern.startsWith(AFFIX_PREFIX) || !pattern.endsWith(AFFIX_SUFFIX)) return;
+  const body = pattern.slice(AFFIX_PREFIX.length, pattern.length - AFFIX_SUFFIX.length);
+  const splitAt = body.indexOf(AFFIX_MARKER);
+  if (splitAt <= 0) return;
+  const left = body.slice(0, splitAt);
+  const right = body.slice(splitAt + AFFIX_MARKER.length);
+  if (left !== right) return;
+  return unescapeRegexp(left);
+}
+
+function escapeRegexp(value: string): string {
+  return value.replaceAll(/[\\^$.*+?()[\]{}|]/g, (character) => `\\${character}`);
+}
+
+function unescapeRegexp(value: string): string {
+  return value.replaceAll(/\\(.)/g, (match) => match.slice(1));
 }
 
 function withoutKeys(
@@ -464,13 +356,3 @@ function withoutKeys(
   }
   return next;
 }
-
-function integerField(value: string): number | undefined {
-  if (!/^-?\d+$/.test(value)) return;
-  const parsed = Number(value);
-  return Number.isSafeInteger(parsed) ? parsed : undefined;
-}
-
-function integerText(value: unknown): string {
-  return typeof value === 'number' && Number.isSafeInteger(value) ? String(value) : '';
-}
diff --git a/frontend/src/studio/studioService.ts b/frontend/src/studio/studioService.ts
index 85332cb6..795df818 100644
--- a/frontend/src/studio/studioService.ts
+++ b/frontend/src/studio/studioService.ts
@@ -26,18 +26,23 @@ export interface StudioValidationOutcome {
   readonly yaml: string | undefined;
 }
 
+export interface StudioSampleItem {
+  readonly title: string;
+  readonly url: string | undefined;
+  readonly publishedAt: string | undefined;
+  readonly imageUrl: string | undefined;
+}
+
 export interface StudioPreview {
   readonly itemCount: number;
-  readonly titles: readonly string[];
-  readonly warnings: readonly string[];
+  readonly items: readonly StudioSampleItem[];
+  readonly nativeFeedUrl: string | undefined;
   readonly failureKind: string | undefined;
 }
 
 export interface StudioSuggestion {
   readonly itemsSelector: string;
   readonly enhance: boolean;
-  readonly segmentStrategy: string;
-  readonly chromeDrops: number;
 }
 
 export class StudioRequestError extends Error {
@@ -67,15 +72,7 @@ export function validateStudioSelectors(
   draft: StudioDraft,
   signal?: AbortSignal
 ): Promise<StudioValidationOutcome> {
-  return validateStudio(token, { selectors: selectorsFromDraft(draft) }, signal);
-}
-
-export function validateStudioYaml(
-  token: string,
-  yaml: string,
-  signal?: AbortSignal
-): Promise<StudioValidationOutcome> {
-  return validateStudio(token, { yaml }, signal);
+  return validateStudio(token, selectorsFromDraft(draft), signal);
 }
 
 export async function previewStudioFeed(
@@ -105,10 +102,10 @@ export async function suggestStudioSelectors(
 
 async function validateStudio(
   token: string,
-  body: { readonly selectors: Record<string, unknown> } | { readonly yaml: string },
+  selectors: Record<string, unknown>,
   signal?: AbortSignal
 ): Promise<StudioValidationOutcome> {
-  return parseValidation(await postJson('feeds/validate', token, body, signal));
+  return parseValidation(await postJson('feeds/validate', token, { selectors }, signal));
 }
 
 async function postJson(path: string, token: string, body: unknown, signal?: AbortSignal): Promise<unknown> {
@@ -210,34 +207,46 @@ function parsePreview(data: unknown): StudioPreview {
     throw new StudioRequestError(COPY.unableToCompleteCreation);
   }
 
-  const titles: string[] = [];
-  for (const item of data.sample_items) {
-    if (!isPlainRecord(item) || typeof item.title !== 'string') {
-      throw new StudioRequestError(COPY.unableToCompleteCreation);
-    }
-    titles.push(item.title);
-  }
-
   return {
     itemCount: data.item_count,
-    titles,
-    warnings: parseWarnings(data.quality_report),
+    items: data.sample_items.map((item) => parseSampleItem(item)),
+    nativeFeedUrl: parseNativeFeed(data.quality_report),
     failureKind: parseFailureKind(data.failure_kind),
   };
 }
 
-function parseWarnings(value: unknown): readonly string[] {
-  if (isAbsent(value)) return [];
-  if (!isPlainRecord(value) || !Array.isArray(value.warnings)) {
+function parseSampleItem(value: unknown): StudioSampleItem {
+  if (!isPlainRecord(value) || typeof value.title !== 'string') {
     throw new StudioRequestError(COPY.unableToCompleteCreation);
   }
 
-  const warnings: string[] = [];
-  for (const warning of value.warnings) {
-    if (typeof warning !== 'string') throw new StudioRequestError(COPY.unableToCompleteCreation);
-    warnings.push(warning);
-  }
-  return warnings;
+  return {
+    title: value.title,
+    url: optionalText(value.url),
+    publishedAt: optionalText(value.published_at),
+    imageUrl: optionalImageUrl(value.image),
+  };
+}
+
+function parseNativeFeed(value: unknown): string | undefined {
+  if (isAbsent(value)) return;
+  if (!isPlainRecord(value)) throw new StudioRequestError(COPY.unableToCompleteCreation);
+  if (!Object.hasOwn(value, 'native_feed') || isAbsent(value.native_feed)) return;
+  return optionalText(value.native_feed);
+}
+
+function optionalImageUrl(value: unknown): string | undefined {
+  if (typeof value !== 'string') return;
+  const trimmed = value.trim();
+  if (trimmed.startsWith('https://') || trimmed.startsWith('http://')) return trimmed;
+  return;
+}
+
+function optionalText(value: unknown): string | undefined {
+  if (isAbsent(value)) return;
+  if (typeof value !== 'string') throw new StudioRequestError(COPY.unableToCompleteCreation);
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
 }
 
 function parseFailureKind(value: unknown): string | undefined {
@@ -255,17 +264,10 @@ function parseSuggestion(data: unknown): StudioSuggestion {
   }
 
   const enhance = typeof data.enhance === 'boolean' ? data.enhance : (draft?.enhance ?? false);
-  const segmentStrategy = typeof data.segment_strategy === 'string' ? data.segment_strategy : '';
-  const chromeDrops =
-    isPlainRecord(data.admission_drops) && typeof data.admission_drops.chrome === 'number'
-      ? data.admission_drops.chrome
-      : 0;
 
   return {
     itemsSelector: draft?.itemsSelector ?? '',
     enhance,
-    segmentStrategy,
-    chromeDrops,
   };
 }
 
diff --git a/frontend/src/studio/useStudio.ts b/frontend/src/studio/useStudio.ts
index 315a080b..192761b0 100644
--- a/frontend/src/studio/useStudio.ts
+++ b/frontend/src/studio/useStudio.ts
@@ -6,73 +6,80 @@ import {
   StudioRequestError,
   suggestStudioSelectors,
   validateStudioSelectors,
-  validateStudioYaml,
   type StudioIssue,
   type StudioPreview,
   type StudioSuggestion,
   type StudioValidationOutcome,
 } from './studioService';
 import {
-  addAttribute,
-  addPostProcessor,
   applyItemsSuggestion,
   emptyDraft,
-  removeAttribute,
-  removePostProcessor,
-  renamePostProcessor,
-  reuseDraftIds,
   selectorsFromDraft,
-  updateAttribute,
-  updatePostProcessorField,
   withEnhance,
+  withFieldFixup,
+  withFieldSelector,
   withItemsSelector,
-  type AttributePatch,
-  type PostProcessorField,
-  type PostProcessorName,
+  type FieldFixup,
   type StudioDraft,
+  type StudioFieldId,
 } from './selectorDraft';
 
 export const STUDIO_VALIDATE_DELAY_MS = 300;
+export const STUDIO_PREVIEW_SETTLE_MS = 800;
 
 interface StudioDocument {
   readonly draft: StudioDraft;
   readonly yaml: string;
+  readonly live: LivePreview;
 }
 
+export type LivePreview =
+  | { readonly status: 'idle' }
+  | { readonly status: 'loading' }
+  | { readonly status: 'ready'; readonly sample: StudioPreview }
+  | { readonly status: 'failed'; readonly message: string };
+
 export type StudioState =
   | (StudioDocument & { readonly phase: 'editing'; readonly validated: boolean })
   | (StudioDocument & { readonly phase: 'validating' })
   | (StudioDocument & { readonly phase: 'invalid'; readonly issues: readonly StudioIssue[] })
-  | (StudioDocument & { readonly phase: 'previewing' })
-  | (StudioDocument & { readonly phase: 'previewed'; readonly preview: StudioPreview })
   | (StudioDocument & { readonly phase: 'saving' })
   | (StudioDocument & { readonly phase: 'failed'; readonly message: string });
 
-type EditSource = 'selectors' | 'yaml';
-
 interface UseStudioOptions {
   readonly url: string;
   readonly token: string;
   readonly validateDelayMs?: number;
+  readonly previewSettleMs?: number;
 }
 
-export function useStudio({ url, token, validateDelayMs = STUDIO_VALIDATE_DELAY_MS }: UseStudioOptions) {
+export function useStudio({
+  url,
+  token,
+  validateDelayMs = STUDIO_VALIDATE_DELAY_MS,
+  previewSettleMs = STUDIO_PREVIEW_SETTLE_MS,
+}: UseStudioOptions) {
   const [state, setState] = useState<StudioState>({
     phase: 'editing',
     draft: emptyDraft(),
     yaml: '',
     validated: false,
+    live: { status: 'idle' },
   });
-  const [suggestion, setSuggestion] = useState<StudioSuggestion | undefined>(undefined);
   const [documentRevision, setDocumentRevision] = useState(0);
 
   const stateReference = useRef(state);
   stateReference.current = state;
-  const editSourceReference = useRef<EditSource>('selectors');
   const requestIdReference = useRef(0);
   const previewRequestReference = useRef(0);
   const suggestRequestReference = useRef(0);
   const saveRequestReference = useRef(0);
+  const previewTimerReference = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+  const previewAbortReference = useRef<AbortController | undefined>(undefined);
+  const enhanceTouchedReference = useRef(false);
+  const itemsTouchedReference = useRef(false);
+  const previewSettleReference = useRef(previewSettleMs);
+  previewSettleReference.current = previewSettleMs;
 
   useEffect(() => {
     const requestId = ++requestIdReference.current;
@@ -85,150 +92,162 @@ export function useStudio({ url, token, validateDelayMs = STUDIO_VALIDATE_DELAY_
       clearTimeout(timer);
       controller.abort();
     };
-  }, [documentRevision, token, validateDelayMs]);
+  }, [documentRevision, token, url, validateDelayMs]);
+
+  useEffect(() => {
+    const requestId = ++suggestRequestReference.current;
+    const controller = new AbortController();
+    void loadEnhanceEvidence(requestId, controller.signal);
+
+    return () => {
+      controller.abort();
+    };
+  }, [url, token]);
+
+  useEffect(() => {
+    return () => {
+      clearTimeout(previewTimerReference.current);
+      previewAbortReference.current?.abort();
+    };
+  }, []);
+
+  async function loadEnhanceEvidence(requestId: number, signal: AbortSignal) {
+    try {
+      const evidence = await suggestStudioSelectors(
+        token,
+        url,
+        stateReference.current.draft.itemsSelector,
+        signal
+      );
+      if (signal.aborted || suggestRequestReference.current !== requestId) return;
+      const next = prefillFromSuggestion(
+        stateReference.current.draft,
+        evidence,
+        itemsTouchedReference.current,
+        enhanceTouchedReference.current
+      );
+      if (next === stateReference.current.draft) return;
+      editSelectors((draft) =>
+        prefillFromSuggestion(draft, evidence, itemsTouchedReference.current, enhanceTouchedReference.current)
+      );
+    } catch (error) {
+      if (isAbortError(error) || signal.aborted || suggestRequestReference.current !== requestId) return;
+    }
+  }
 
   async function runValidate(requestId: number, signal: AbortSignal) {
-    const source = editSourceReference.current;
     const sentDraft = stateReference.current.draft;
-    const sentYaml = stateReference.current.yaml;
-    setState((previous) => ({ phase: 'validating', draft: previous.draft, yaml: previous.yaml }));
+    cancelPreview();
+    setState((previous) => ({
+      phase: 'validating',
+      draft: previous.draft,
+      yaml: previous.yaml,
+      live: previous.live,
+    }));
 
     try {
-      const outcome =
-        source === 'yaml'
-          ? await validateStudioYaml(token, sentYaml, signal)
-          : await validateStudioSelectors(token, sentDraft, signal);
+      const outcome = await validateStudioSelectors(token, sentDraft, signal);
       if (signal.aborted || requestIdReference.current !== requestId) return;
-      commitValidation(outcome, source, sentDraft, sentYaml);
+      commitValidation(outcome, sentDraft);
     } catch (error) {
       if (isAbortError(error) || signal.aborted || requestIdReference.current !== requestId) return;
       setState((previous) => ({
         phase: 'failed',
         draft: previous.draft,
         yaml: previous.yaml,
+        live: { status: 'idle' },
         message: error instanceof StudioRequestError ? error.message : COPY.unableToReachServer,
       }));
     }
   }
 
-  function commitValidation(
-    outcome: StudioValidationOutcome,
-    source: EditSource,
-    sentDraft: StudioDraft,
-    sentYaml: string
-  ) {
-    const syntaxError = outcome.issues.some((issue) => issue.code === 'parse');
-    let draft = sentDraft;
-    let yaml = sentYaml;
-
-    if (source === 'yaml') {
-      if (!syntaxError && outcome.draft) draft = reuseDraftIds(sentDraft, outcome.draft, false);
-      if (!syntaxError && outcome.yaml !== undefined) yaml = outcome.yaml;
-    } else if (outcome.draft) {
-      draft = reuseDraftIds(sentDraft, outcome.draft, true);
-      if (outcome.yaml !== undefined) yaml = outcome.yaml;
-    } else if (outcome.yaml !== undefined) {
-      yaml = outcome.yaml;
-    }
+  function commitValidation(outcome: StudioValidationOutcome, sentDraft: StudioDraft) {
+    const draft = outcome.draft ? adoptServerDraft(sentDraft, outcome.draft) : sentDraft;
+    const yaml = outcome.yaml ?? stateReference.current.yaml;
 
-    if (syntaxError || !outcome.valid) {
-      setState({ phase: 'invalid', draft, yaml, issues: outcome.issues });
+    if (!outcome.valid) {
+      setState({ phase: 'invalid', draft, yaml, issues: outcome.issues, live: { status: 'idle' } });
       return;
     }
 
-    setState({ phase: 'editing', draft, yaml, validated: true });
+    setState({ phase: 'editing', draft, yaml, validated: true, live: { status: 'idle' } });
+    schedulePreview();
   }
 
   function editSelectors(update: (draft: StudioDraft) => StudioDraft) {
-    editSourceReference.current = 'selectors';
-    previewRequestReference.current += 1;
+    cancelPreview();
     setState((previous) => ({
       phase: 'editing',
       draft: update(previous.draft),
       yaml: previous.yaml,
       validated: false,
+      live: { status: 'idle' },
     }));
     setDocumentRevision((revision) => revision + 1);
   }
 
-  const setItemsSelector = (itemsSelector: string) => {
-    editSelectors((draft) => withItemsSelector(draft, itemsSelector));
-  };
-
-  const setEnhance = (isEnhanced: boolean) => {
-    editSelectors((draft) => withEnhance(draft, isEnhanced));
-  };
+  function cancelPreview() {
+    clearTimeout(previewTimerReference.current);
+    previewAbortReference.current?.abort();
+    previewAbortReference.current = undefined;
+    previewRequestReference.current += 1;
+  }
 
-  const appendAttribute = () => {
-    editSelectors((draft) => addAttribute(draft));
-  };
+  function schedulePreview() {
+    cancelPreview();
+    const requestId = previewRequestReference.current;
+    previewTimerReference.current = setTimeout(() => {
+      void runPreview(requestId);
+    }, previewSettleReference.current);
+  }
 
-  const changeAttribute = (attributeId: string, patch: AttributePatch) => {
-    editSelectors((draft) => updateAttribute(draft, attributeId, patch));
-  };
+  async function runPreview(requestId: number) {
+    const current = stateReference.current;
+    if (!(current.phase === 'editing' && current.validated)) return;
+    if (previewRequestReference.current !== requestId) return;
 
-  const deleteAttribute = (attributeId: string) => {
-    editSelectors((draft) => removeAttribute(draft, attributeId));
-  };
+    const controller = new AbortController();
+    previewAbortReference.current = controller;
+    setState((previous) => {
+      if (!(previous.phase === 'editing' && previous.validated)) return previous;
+      if (previewRequestReference.current !== requestId) return previous;
+      return assignLive(previous, { status: 'loading' });
+    });
 
-  const appendPostProcessor = (attributeId: string) => {
-    editSelectors((draft) => addPostProcessor(draft, attributeId));
-  };
+    try {
+      const sample = await previewStudioFeed(token, url, stateReference.current.draft, controller.signal);
+      if (controller.signal.aborted || previewRequestReference.current !== requestId) return;
+      if (sample.failureKind === 'execution') {
+        setState((previous) => assignLive(previous, { status: 'failed', message: COPY.previewUnavailable }));
+        return;
+      }
+      setState((previous) => assignLive(previous, { status: 'ready', sample }));
+    } catch (error) {
+      if (isAbortError(error) || controller.signal.aborted || previewRequestReference.current !== requestId)
+        return;
+      const message = error instanceof StudioRequestError ? error.message : COPY.unableToReachServer;
+      setState((previous) => assignLive(previous, { status: 'failed', message }));
+    }
+  }
 
-  const deletePostProcessor = (attributeId: string, processorId: string) => {
-    editSelectors((draft) => removePostProcessor(draft, attributeId, processorId));
+  const setItemsSelector = (itemsSelector: string) => {
+    itemsTouchedReference.current = true;
+    editSelectors((draft) => withItemsSelector(draft, itemsSelector));
   };
 
-  const changePostProcessorName = (attributeId: string, processorId: string, name: PostProcessorName) => {
-    editSelectors((draft) => renamePostProcessor(draft, attributeId, processorId, name));
+  const setEnhance = (isEnhanced: boolean) => {
+    enhanceTouchedReference.current = true;
+    editSelectors((draft) => withEnhance(draft, isEnhanced));
   };
 
-  const changePostProcessorField = (
-    attributeId: string,
-    processorId: string,
-    field: PostProcessorField,
-    value: string
-  ) => {
-    editSelectors((draft) => updatePostProcessorField(draft, attributeId, processorId, field, value));
+  const setFieldSelector = (field: StudioFieldId, selector: string) => {
+    editSelectors((draft) => withFieldSelector(draft, field, selector));
   };
 
-  const setYaml = (yaml: string) => {
-    editSourceReference.current = 'yaml';
-    previewRequestReference.current += 1;
-    setState((previous) => ({
-      phase: 'editing',
-      draft: previous.draft,
-      yaml,
-      validated: false,
-    }));
-    setDocumentRevision((revision) => revision + 1);
+  const setFieldFixup = (field: StudioFieldId, fixup: FieldFixup) => {
+    editSelectors((draft) => withFieldFixup(draft, field, fixup));
   };
 
-  async function requestPreview() {
-    const requestId = ++previewRequestReference.current;
-    const controller = new AbortController();
-    setState((previous) => ({ phase: 'previewing', draft: previous.draft, yaml: previous.yaml }));
-
-    try {
-      const preview = await previewStudioFeed(token, url, stateReference.current.draft, controller.signal);
-      if (previewRequestReference.current !== requestId) return;
-      setState((previous) => ({
-        phase: 'previewed',
-        draft: previous.draft,
-        yaml: previous.yaml,
-        preview,
-      }));
-    } catch (error) {
-      if (isAbortError(error) || previewRequestReference.current !== requestId) return;
-      setState((previous) => ({
-        phase: 'failed',
-        draft: previous.draft,
-        yaml: previous.yaml,
-        message: error instanceof StudioRequestError ? error.message : COPY.unableToReachServer,
-      }));
-    }
-  }
-
   async function requestSuggestion() {
     const requestId = ++suggestRequestReference.current;
     try {
@@ -238,7 +257,8 @@ export function useStudio({ url, token, validateDelayMs = STUDIO_VALIDATE_DELAY_
         stateReference.current.draft.itemsSelector
       );
       if (suggestRequestReference.current !== requestId) return;
-      setSuggestion(nextSuggestion);
+      itemsTouchedReference.current = true;
+      enhanceTouchedReference.current = true;
       editSelectors((draft) =>
         applyItemsSuggestion(draft, nextSuggestion.itemsSelector, nextSuggestion.enhance)
       );
@@ -248,15 +268,24 @@ export function useStudio({ url, token, validateDelayMs = STUDIO_VALIDATE_DELAY_
         phase: 'failed',
         draft: previous.draft,
         yaml: previous.yaml,
+        live: previous.live,
         message: error instanceof StudioRequestError ? error.message : COPY.unableToReachServer,
       }));
     }
   }
 
+  function retryPreview() {
+    const current = stateReference.current;
+    if (!(current.phase === 'editing' && current.validated)) return;
+    cancelPreview();
+    const requestId = previewRequestReference.current;
+    void runPreview(requestId);
+  }
+
   async function save(create: (selectors: Record<string, unknown>) => Promise<void>) {
     const requestId = ++saveRequestReference.current;
     const current = stateReference.current;
-    setState({ phase: 'saving', draft: current.draft, yaml: current.yaml });
+    setState({ phase: 'saving', draft: current.draft, yaml: current.yaml, live: current.live });
 
     try {
       await create(selectorsFromDraft(current.draft));
@@ -266,6 +295,7 @@ export function useStudio({ url, token, validateDelayMs = STUDIO_VALIDATE_DELAY_
         phase: 'failed',
         draft: current.draft,
         yaml: current.yaml,
+        live: current.live,
         message: failureMessage(error),
       });
     }
@@ -273,24 +303,14 @@ export function useStudio({ url, token, validateDelayMs = STUDIO_VALIDATE_DELAY_
 
   return {
     state,
-    suggestion,
     setItemsSelector,
     setEnhance,
-    appendAttribute,
-    changeAttribute,
-    deleteAttribute,
-    appendPostProcessor,
-    deletePostProcessor,
-    changePostProcessorName,
-    changePostProcessorField,
-    setYaml,
-    requestPreview: () => {
-      void requestPreview();
-    },
+    setFieldSelector,
+    setFieldFixup,
     requestSuggestion: () => {
       void requestSuggestion();
     },
-    selectorsDocument: () => selectorsFromDraft(stateReference.current.draft),
+    retryPreview,
     save,
   };
 }
@@ -299,8 +319,58 @@ export function studioIssues(state: StudioState): readonly StudioIssue[] {
   return state.phase === 'invalid' ? state.issues : [];
 }
 
-export function hasSyntaxError(state: StudioState): boolean {
-  return state.phase === 'invalid' && state.issues.some((issue) => issue.code === 'parse');
+export function canSaveStudio(state: StudioState): boolean {
+  return state.phase === 'editing' && state.validated;
+}
+
+function prefillFromSuggestion(
+  draft: StudioDraft,
+  suggestion: StudioSuggestion,
+  isItemsTouched: boolean,
+  isEnhanceTouched: boolean
+): StudioDraft {
+  const canFillItems =
+    !isItemsTouched && draft.itemsSelector.trim().length === 0 && suggestion.itemsSelector.length > 0;
+  const itemsSelector = (canFillItems ? suggestion : draft).itemsSelector;
+  const enhance = (isEnhanceTouched ? draft : suggestion).enhance;
+  if (itemsSelector === draft.itemsSelector && enhance === draft.enhance) return draft;
+  return applyItemsSuggestion(draft, itemsSelector, enhance);
+}
+
+function adoptServerDraft(sent: StudioDraft, incoming: StudioDraft): StudioDraft {
+  return {
+    ...sent,
+    itemsSelector: incoming.itemsSelector,
+    enhance: incoming.enhance,
+    preserved: incoming.preserved,
+    itemsPreserved: incoming.itemsPreserved,
+  };
+}
+
+function assignLive(state: StudioState, live: LivePreview): StudioState {
+  switch (state.phase) {
+    case 'editing': {
+      return {
+        phase: 'editing',
+        draft: state.draft,
+        yaml: state.yaml,
+        validated: state.validated,
+        live,
+      };
+    }
+    case 'validating': {
+      return { phase: 'validating', draft: state.draft, yaml: state.yaml, live };
+    }
+    case 'invalid': {
+      return { phase: 'invalid', draft: state.draft, yaml: state.yaml, issues: state.issues, live };
+    }
+    case 'saving': {
+      return { phase: 'saving', draft: state.draft, yaml: state.yaml, live };
+    }
+    case 'failed': {
+      return { phase: 'failed', draft: state.draft, yaml: state.yaml, message: state.message, live };
+    }
+  }
 }
 
 function failureMessage(error: unknown): string {
diff --git a/frontend/src/styles/main.css b/frontend/src/styles/main.css
index c104129a..6171a8e6 100644
--- a/frontend/src/styles/main.css
+++ b/frontend/src/styles/main.css
@@ -572,8 +572,58 @@
   }
 }
 
-.studio-yaml {
-  min-height: calc(var(--space-7) * 4);
+.refine-columns {
+  display: flex;
+  flex-direction: row;
+  align-items: flex-start;
+  gap: var(--space-4);
+}
+
+.refine-pane {
+  flex: 1;
+  min-width: 0;
+}
+
+.refine-columns .field-help {
+  text-align: start;
+}
+
+.refine-action {
+  width: 100%;
+}
+
+.refine-check {
+  justify-self: start;
+  width: auto;
+}
+
+.refine-sample-image {
+  display: block;
+  width: 100%;
+  max-height: calc(var(--space-7) * 3);
+  margin: 0;
+  object-fit: cover;
+  border-radius: var(--radius-md);
+}
+
+.refine-status {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space-2);
+}
+
+.refine-yaml {
+  margin: 0;
+  max-height: calc(var(--space-7) * 4);
+  overflow: auto;
+  padding: var(--space-3);
+  white-space: pre-wrap;
+}
+
+@media (width < 48rem) {
+  .refine-columns {
+    flex-direction: column;
+  }
 }
 
 @keyframes spin {
diff --git a/public/openapi.yaml b/public/openapi.yaml
index 1cd05169..b1ba6bf1 100644
--- a/public/openapi.yaml
+++ b/public/openapi.yaml
@@ -611,6 +611,9 @@ paths:
                       sample_items:
                         items:
                           properties:
+                            image:
+                              nullable: true
+                              type: string
                             title:
                               type: string
                           required:
diff --git a/spec/html2rss/web/api/v1_spec.rb b/spec/html2rss/web/api/v1_spec.rb
index a62b9e8f..6b23ee17 100644
--- a/spec/html2rss/web/api/v1_spec.rb
+++ b/spec/html2rss/web/api/v1_spec.rb
@@ -934,6 +934,21 @@ def post_validate(payload)
       )
     end
 
+    def imaged_preview_result
+      preview_result.with(
+        sample_items: [{ 'title' => 'A' }, { 'title' => 'Plain' }, { 'title' => 'Enclosed' }],
+        rss: %(<rss version="2.0"><channel><title>t</title>#{imaged_items}</channel></rss>)
+      )
+    end
+
+    def imaged_items
+      [
+        '<item><title>A</title><description>&lt;img src="https://cdn.example/a.jpg"&gt;</description></item>',
+        '<item><title>Plain</title><enclosure url="https://cdn.example/b.mp3" type="audio/mpeg" length="1"/></item>',
+        '<item><title>Enclosed</title><enclosure url="https://cdn.example/c.jpg" type="image/jpeg" length="2"/></item>'
+      ].join
+    end
+
     before do
       allow(Html2rss).to receive(:test).and_return(preview_result)
     end
@@ -961,6 +976,19 @@ def post_validate(payload)
       expect(json.dig('data', 'quality_report', 'warnings')).to eq(['short_titles'])
     end
 
+    it 'adds one image url per sample item and still omits the rss document', :aggregate_failures do
+      allow(Html2rss).to receive(:test).and_return(imaged_preview_result)
+      header 'Authorization', "Bearer #{admin_token}"
+      header 'Content-Type', 'application/json'
+      post '/api/v1/feeds/preview', { url: feed_url, selectors: { items: { selector: 'article' } } }.to_json
+
+      json = expect_success_response(last_response)
+      expect(json.dig('data', 'sample_items').map { it['image'] }).to eq(
+        ['https://cdn.example/a.jpg', nil, 'https://cdn.example/c.jpg']
+      )
+      expect(json.fetch('data').keys).not_to include('rss')
+    end
+
     it 'previews through the token generator config' do
       header 'Authorization', "Bearer #{admin_token}"
       header 'Content-Type', 'application/json'

From 2208596ae300795b34713147fa0fff18edb35d95 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 20 Sep 2026 02:04:41 +0200
Subject: [PATCH 029/108] fix(frontend): pin generated OpenAPI client to
 same-origin base URL

Stop codegen from baking api.html2rss.dev into the SPA client. Requests go through a same-origin /api/v1 unwrap so Node Request can resolve against location.origin.
---
 frontend/eslint.config.js                     | 18 ++++++++
 frontend/openapi-ts.config.ts                 | 12 +++++
 frontend/package.json                         |  4 +-
 frontend/src/__tests__/apiHttp.client.test.ts | 45 +++++++++++++++++++
 frontend/src/api/generated/client.gen.ts      |  2 +-
 frontend/src/api/http/client.ts               | 42 +++++++++++++++++
 6 files changed, 120 insertions(+), 3 deletions(-)
 create mode 100644 frontend/openapi-ts.config.ts
 create mode 100644 frontend/src/__tests__/apiHttp.client.test.ts
 create mode 100644 frontend/src/api/http/client.ts

diff --git a/frontend/eslint.config.js b/frontend/eslint.config.js
index 932c2b50..ceac7928 100644
--- a/frontend/eslint.config.js
+++ b/frontend/eslint.config.js
@@ -33,6 +33,24 @@ export default tseslint.config(
       '@typescript-eslint/no-explicit-any': 'off',
       'unicorn/filename-case': 'off',
       'unicorn/better-regex': 'warn',
+      'no-restricted-imports': [
+        'error',
+        {
+          patterns: [
+            {
+              group: ['**/api/generated', '**/api/generated/**'],
+              allowTypeImports: true,
+              message: 'Value-import the generated OpenAPI client only from src/api/http/*.ts.',
+            },
+          ],
+        },
+      ],
+    },
+  },
+  {
+    files: ['src/api/http/*.ts', 'src/__tests__/apiHttp*.test.ts'],
+    rules: {
+      'no-restricted-imports': 'off',
     },
   }
 );
diff --git a/frontend/openapi-ts.config.ts b/frontend/openapi-ts.config.ts
new file mode 100644
index 00000000..c2e01975
--- /dev/null
+++ b/frontend/openapi-ts.config.ts
@@ -0,0 +1,12 @@
+import { defineConfig } from '@hey-api/openapi-ts';
+
+export default defineConfig({
+  input: '../public/openapi.yaml',
+  output: 'src/api/generated',
+  plugins: [
+    {
+      name: '@hey-api/client-fetch',
+      baseUrl: '/api/v1',
+    },
+  ],
+});
diff --git a/frontend/package.json b/frontend/package.json
index d05984e2..61d86cdb 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -14,8 +14,8 @@
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "typecheck": "tsc -p tsconfig.typecheck.json --noEmit",
-    "openapi:generate": "openapi-ts -i ../public/openapi.yaml -o src/api/generated -c @hey-api/client-fetch",
-    "openapi:verify": "openapi-ts -i ../public/openapi.yaml -o src/api/generated -c @hey-api/client-fetch && git diff --exit-code -- src/api/generated",
+    "openapi:generate": "openapi-ts",
+    "openapi:verify": "openapi-ts && git diff --exit-code -- src/api/generated",
     "test": "vitest",
     "test:run": "vitest run",
     "test:unit": "vitest run --reporter=verbose --config vitest.unit.config.ts",
diff --git a/frontend/src/__tests__/apiHttp.client.test.ts b/frontend/src/__tests__/apiHttp.client.test.ts
new file mode 100644
index 00000000..6ab95e52
--- /dev/null
+++ b/frontend/src/__tests__/apiHttp.client.test.ts
@@ -0,0 +1,45 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { getApiMetadata } from '../api/generated/sdk.gen';
+import { httpRequestUrl, jsonBaseUrl, unwrap } from '../api/http/client';
+
+describe('generated OpenAPI client', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('pins requests to same-origin /api/v1 and never api.html2rss.dev', async () => {
+    const fetchMock = vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+      Response.json({
+        success: true,
+        data: {
+          api: { name: 'html2rss-web API', description: 'd', openapi_url: '/openapi.yaml' },
+          instance: { feed_creation: { enabled: true, access_token_required: true } },
+        },
+      })
+    );
+
+    const envelope = await unwrap(getApiMetadata({ baseUrl: jsonBaseUrl() }));
+    const input = fetchMock.mock.calls[0]?.[0];
+    expect(input).toBeInstanceOf(Request);
+    if (!(input instanceof Request)) return;
+
+    const requested = httpRequestUrl(input);
+    expect(requested.host).not.toBe('api.html2rss.dev');
+    expect(requested.pathname).toMatch(/^\/api\/v1\/?$/);
+    expect(envelope).toMatchObject({ ok: true, status: 200 });
+    expect(envelope.body).toMatchObject({ success: true });
+  });
+
+  it('unwraps HTTP errors into ok/status/body without throwing', async () => {
+    vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+      Response.json({ error: 'catalog_disabled' }, { status: 404 })
+    );
+
+    const envelope = await unwrap(getApiMetadata({ baseUrl: jsonBaseUrl() }));
+    expect(envelope).toMatchObject({
+      ok: false,
+      status: 404,
+      body: { error: 'catalog_disabled' },
+    });
+  });
+});
diff --git a/frontend/src/api/generated/client.gen.ts b/frontend/src/api/generated/client.gen.ts
index 97c964c5..5276b939 100644
--- a/frontend/src/api/generated/client.gen.ts
+++ b/frontend/src/api/generated/client.gen.ts
@@ -13,4 +13,4 @@ import type { ClientOptions as ClientOptions2 } from './types.gen';
  */
 export type CreateClientConfig<T extends ClientOptions = ClientOptions2> = (override?: Config<ClientOptions & T>) => Config<Required<ClientOptions> & T>;
 
-export const client: Client = createClient(createConfig<ClientOptions2>({ baseUrl: 'https://api.html2rss.dev/api/v1' }));
+export const client: Client = createClient(createConfig<ClientOptions2>({ baseUrl: '/api/v1' }));
diff --git a/frontend/src/api/http/client.ts b/frontend/src/api/http/client.ts
new file mode 100644
index 00000000..c48af0e1
--- /dev/null
+++ b/frontend/src/api/http/client.ts
@@ -0,0 +1,42 @@
+export type HttpEnvelope = {
+  readonly ok: boolean;
+  readonly status: number;
+  readonly body: unknown;
+};
+
+type SdkFields = {
+  data?: unknown;
+  error?: unknown;
+  response?: Response;
+};
+
+/** Same-origin JSON API prefix. Absolute when `location.origin` exists so `Request` can parse it. */
+export function jsonBaseUrl(): string {
+  return location.origin ? `${location.origin}/api/v1` : '/api/v1';
+}
+
+/**
+ * Maps Hey API `{ data, error, response }` into a closed `{ ok, status, body }` envelope.
+ * Network failures and missing responses are `ok: false` with status `0`.
+ */
+export async function unwrap(result: Promise<SdkFields>): Promise<HttpEnvelope> {
+  try {
+    const { data, error, response } = await result;
+    if (!response) return { ok: false, status: 0, body: error };
+
+    return {
+      ok: response.ok,
+      status: response.status,
+      body: response.ok ? data : (error ?? data),
+    };
+  } catch (error) {
+    return { ok: false, status: 0, body: error };
+  }
+}
+
+/** Resolve Hey API's Request/URL fetch argument for host and path checks. */
+export function httpRequestUrl(input: RequestInfo | URL): URL {
+  if (input instanceof URL) return input;
+  if (typeof input === 'string') return new URL(input, location.origin || 'http://localhost');
+  return new URL(input.url);
+}

From df0dd4101186779060d599c1eeec3b282e1cba79 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 20 Sep 2026 02:10:49 +0200
Subject: [PATCH 030/108] refactor(openapi): extract post-processor with Ruby 4
 idioms

Move the rspec-openapi stringify, deep-sort, and path-normalize hook into one module so the published YAML stays generated from a testable seam. rspec-openapi only invokes a Proc, so the hook stays a lambda.
---
 .../web/openapi_post_processor_spec.rb        |  66 ++++++
 spec/support/openapi.rb                       | 195 +-----------------
 spec/support/openapi_post_processor.rb        | 176 ++++++++++++++++
 3 files changed, 245 insertions(+), 192 deletions(-)
 create mode 100644 spec/html2rss/web/openapi_post_processor_spec.rb
 create mode 100644 spec/support/openapi_post_processor.rb

diff --git a/spec/html2rss/web/openapi_post_processor_spec.rb b/spec/html2rss/web/openapi_post_processor_spec.rb
new file mode 100644
index 00000000..d3327ebd
--- /dev/null
+++ b/spec/html2rss/web/openapi_post_processor_spec.rb
@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe OpenapiPostProcessor do
+  def process_paths(paths)
+    spec = { 'paths' => paths }
+    described_class.call(nil, [], spec)
+    spec['paths']
+  end
+
+  def get_operation(summary: 'ok')
+    { 'get' => { 'summary' => summary, 'responses' => { '200' => { 'description' => summary } } } }
+  end
+
+  describe '.stringify' do
+    it 'stringifies nested hash keys and leaves scalars', :aggregate_failures do
+      expect(described_class.stringify({ a: [{ b: 1 }, :keep] })).to eq(
+        'a' => [{ 'b' => 1 }, :keep]
+      )
+      expect(described_class.stringify('plain')).to eq('plain')
+    end
+  end
+
+  describe '.deep_sort' do
+    it 'sorts nested hash keys without reordering arrays', :aggregate_failures do
+      expect(described_class.deep_sort({ 'z' => 1, 'a' => { 'c' => 2, 'b' => 3 } })).to eq(
+        'a' => { 'b' => 3, 'c' => 2 },
+        'z' => 1
+      )
+      expect(described_class.deep_sort(%w[z a])).to eq(%w[z a])
+    end
+  end
+
+  describe '.call path normalize' do
+    [
+      ['/api/v1', '/'],
+      ['/api/v1/feeds', '/feeds'],
+      ['/api/v1/feeds/validate', '/feeds/validate'],
+      ['/api/v1/feeds/preview', '/feeds/preview'],
+      ['/api/v1/feeds/suggest_selectors', '/feeds/suggest_selectors'],
+      ['/api/v1/feeds/abc123', '/feeds/{token}'],
+      ['/feeds/{token}', '/feeds/{token}']
+    ].each do |raw, expected|
+      it "maps #{raw} to #{expected}" do
+        expect(process_paths(raw => get_operation).keys).to eq([expected])
+      end
+    end
+  end
+
+  it 'merges duplicate operations and injects the token path parameter', :aggregate_failures do
+    paths = process_paths(
+      '/api/v1/feeds/one' => get_operation(summary: 'longer summary text'),
+      '/api/v1/feeds/two' => get_operation(summary: 'short')
+    )
+    get = paths.fetch('/feeds/{token}').fetch('get')
+
+    expect(get['responses'].dig('200', 'description')).to eq('short')
+    expect(get['parameters']).to include(
+      'name' => 'token',
+      'in' => 'path',
+      'required' => true,
+      'schema' => { 'type' => 'string' }
+    )
+  end
+end
diff --git a/spec/support/openapi.rb b/spec/support/openapi.rb
index e0e21d04..4fdb125d 100644
--- a/spec/support/openapi.rb
+++ b/spec/support/openapi.rb
@@ -137,197 +137,8 @@ def section(node, name)
   }
 
   # Keep path keys relative to /api/v1 because servers include the versioned base path.
-  RSpec::OpenAPI.post_process_hook = lambda do |_path, _records, spec|
-    token_feed_error_statuses = %w[401 403 429 500 503 504].freeze
-    token_feed_empty_statuses = %w[422].freeze
-
-    stringify = lambda do |value|
-      case value
-      when Hash
-        value.each_with_object({}) { |(key, nested_value), mapped| mapped[key.to_s] = stringify.call(nested_value) }
-      when Array
-        value.map { |item| stringify.call(item) }
-      else
-        value
-      end
-    end
-
-    deep_sort = lambda do |value|
-      case value
-      when Hash
-        value.keys.sort_by(&:to_s).to_h { |key| [key, deep_sort.call(value[key])] }
-      when Array
-        value.map { |item| deep_sort.call(item) }
-      else
-        value
-      end
-    end
-
-    merge_responses = lambda do |existing_responses, new_responses|
-      canonical_description = lambda do |*responses|
-        descriptions = responses
-                       .filter_map { |response| response['description']&.to_s&.strip }
-                       .reject(&:empty?)
-                       .uniq
-
-        next nil if descriptions.empty?
-
-        # Prefer the most generic/canonical wording when duplicate examples define
-        # the same status differently.
-        descriptions.min_by { |description| [description.length, description] }
-      end
-
-      statuses = existing_responses.keys | new_responses.keys
-
-      statuses.each_with_object({}) do |status, merged_responses|
-        current = existing_responses[status] || {}
-        incoming = new_responses[status] || {}
-        merged_response = current.merge(incoming)
-
-        current_content = current['content'] || {}
-        incoming_content = incoming['content'] || {}
-        if current_content.any? || incoming_content.any?
-          content_types = current_content.keys | incoming_content.keys
-          merged_response['content'] = content_types.to_h do |content_type|
-            current_entry = current_content[content_type] || {}
-            incoming_entry = incoming_content[content_type] || {}
-            [content_type, current_entry.merge(incoming_entry)]
-          end
-        end
-
-        current_headers = current['headers'] || {}
-        incoming_headers = incoming['headers'] || {}
-        if current_headers.any? || incoming_headers.any?
-          merged_response['headers'] = current_headers.merge(incoming_headers)
-        end
-
-        merged_response['description'] = canonical_description.call(current, incoming)
-        merged_responses[status] = merged_response
-      end
-    end
-
-    token_feed_error_examples = {
-      'text/plain' => {
-        'example' => 'Failed to generate feed: Invalid token'
-      }
-    }
-
-    token_feed_empty_examples = {
-      'text/plain' => {
-        'example' => Html2rss::Web::ErrorClassifier::EXTRACTION_EMPTY_MESSAGE
-      }
-    }
-
-    token_feed_error_content = {
-      'text/plain' => {
-        'schema' => { 'type' => 'string' }
-      }.merge(token_feed_error_examples.fetch('text/plain'))
-    }.freeze
-    token_feed_empty_content = {
-      'text/plain' => {
-        'schema' => { 'type' => 'string' }
-      }.merge(token_feed_empty_examples.fetch('text/plain'))
-    }.freeze
-
-    path_map = spec['paths'] || spec[:paths]
-    next unless path_map.is_a?(Hash)
-
-    studio_segment = Regexp.union(Html2rss::Web::Routes::ApiV1::FeedRoutes::STUDIO_POSTS.keys).source
-    token_path = %r{\A/api/v1/feeds/(?!(?:#{studio_segment})\z)[^/]+\z}
-    normalized_paths = {}
-    path_map.each do |raw_path, operation|
-      original_path = raw_path.to_s
-      normalized = if original_path.match?(token_path)
-                     '/feeds/{token}'
-                   elsif original_path.start_with?('/api/v1')
-                     original_path.delete_prefix('/api/v1')
-                   else
-                     original_path
-                   end
-      normalized = '/' if normalized.empty?
-      normalized_paths[normalized] ||= {}
-
-      stringify.call(operation).each do |verb, operation_doc|
-        existing = normalized_paths[normalized][verb]
-
-        if existing
-          merged = existing.merge(operation_doc)
-          merged['responses'] = merge_responses.call(existing['responses'] || {}, operation_doc['responses'] || {})
-          merged['parameters'] = [*(existing['parameters'] || []), *(operation_doc['parameters'] || [])]
-          merged['parameters'].uniq! { |parameter| [parameter['name'], parameter['in']] }
-          normalized_paths[normalized][verb] = deep_sort.call(merged)
-        else
-          normalized_paths[normalized][verb] = deep_sort.call(operation_doc)
-        end
-
-        normalized_paths[normalized][verb]['description'] ||= normalized_paths[normalized][verb]['summary']
-
-        if normalized.start_with?('/feeds/{token}')
-          normalized_paths[normalized][verb]['parameters'] ||= []
-          has_token_param = normalized_paths[normalized][verb]['parameters'].any? do |parameter|
-            parameter['name'] == 'token' && parameter['in'] == 'path'
-          end
-          unless has_token_param
-            normalized_paths[normalized][verb]['parameters'] << {
-              'name' => 'token',
-              'in' => 'path',
-              'required' => true,
-              'schema' => { 'type' => 'string' }
-            }
-          end
-        end
-
-        # Inject Retry-After header for rate limiting and timeout responses
-        %w[429 503 504].each do |status| # rubocop:disable Performance/CollectionLiteralInLoop
-          response = normalized_paths[normalized][verb].dig('responses', status)
-          next unless response
-
-          response['headers'] ||= {}
-          response['headers']['Retry-After'] = {
-            'description' => 'The number of seconds to wait before retrying the request.',
-            'schema' => { 'type' => 'integer' }
-          }
-        end
-
-        next unless normalized == '/feeds/{token}'
-
-        token_feed_error_statuses.each do |status|
-          response = normalized_paths[normalized][verb].dig('responses', status)
-          next unless response
-
-          response['content'] = token_feed_error_content
-        end
-
-        token_feed_empty_statuses.each do |status|
-          response = normalized_paths[normalized][verb].dig('responses', status)
-          next unless response
-
-          response['content'] = token_feed_empty_content
-        end
-      end
-    end
-
-    if spec.key?('paths')
-      spec['paths'] = deep_sort.call(normalized_paths)
-    else
-      spec[:paths] = deep_sort.call(normalized_paths)
-    end
-
-    tags = [
-      { 'name' => 'Root', 'description' => 'API metadata and service-level information.' },
-      { 'name' => 'Catalog', 'description' => 'Public feed-directory catalog metadata.' },
-      { 'name' => 'Health', 'description' => 'Health and readiness endpoints.' },
-      { 'name' => 'Strategies', 'description' => 'Feed extraction strategy discovery.' },
-      { 'name' => 'Feeds', 'description' => 'Feed creation and feed rendering operations.' },
-      { 'name' => 'Studio', 'description' => 'Validate, preview, and suggest refined feed configs.' }
-    ]
-
-    if spec.key?('tags')
-      spec['tags'] = tags
-    else
-      spec[:tags] = tags
-    end
-
-    OpenapiRuntimeContract.stamp(spec)
+  require_relative 'openapi_post_processor'
+  RSpec::OpenAPI.post_process_hook = lambda do |path, records, spec|
+    OpenapiPostProcessor.call(path, records, spec)
   end
 end
diff --git a/spec/support/openapi_post_processor.rb b/spec/support/openapi_post_processor.rb
new file mode 100644
index 00000000..a6725bda
--- /dev/null
+++ b/spec/support/openapi_post_processor.rb
@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+##
+# Normalizes rspec-openapi output: stringify keys, collapse /api/v1 prefixes,
+# merge duplicate operations, and stamp runtime allowlists.
+module OpenapiPostProcessor # rubocop:disable Metrics/ModuleLength -- extracted hook is one seam
+  TAGS = [
+    { 'name' => 'Root', 'description' => 'API metadata and service-level information.' },
+    { 'name' => 'Catalog', 'description' => 'Public feed-directory catalog metadata.' },
+    { 'name' => 'Health', 'description' => 'Health and readiness endpoints.' },
+    { 'name' => 'Strategies', 'description' => 'Feed extraction strategy discovery.' },
+    { 'name' => 'Feeds', 'description' => 'Feed creation and feed rendering operations.' },
+    { 'name' => 'Studio', 'description' => 'Validate, preview, and suggest refined feed configs.' }
+  ].freeze
+  RETRY_AFTER_STATUSES = %w[429 503 504].freeze
+  TOKEN_FEED_ERROR_STATUSES = %w[401 403 429 500 503 504].freeze
+  TOKEN_FEED_EMPTY_STATUSES = %w[422].freeze
+  TOKEN_FEED_ERROR_CONTENT = {
+    'text/plain' => { 'schema' => { 'type' => 'string' }, 'example' => 'Failed to generate feed: Invalid token' }
+  }.freeze
+  TOKEN_FEED_EMPTY_CONTENT = {
+    'text/plain' => {
+      'schema' => { 'type' => 'string' },
+      'example' => Html2rss::Web::ErrorClassifier::EXTRACTION_EMPTY_MESSAGE
+    }
+  }.freeze
+
+  module_function
+
+  def call(_path, _records, spec)
+    path_map = spec['paths'] || spec[:paths]
+    return unless path_map.is_a?(Hash)
+
+    spec[spec.key?('paths') ? 'paths' : :paths] = deep_sort(normalize_paths(path_map))
+    spec[spec.key?('tags') ? 'tags' : :tags] = TAGS
+    OpenapiRuntimeContract.stamp(spec)
+  end
+
+  def stringify(value)
+    case value
+    in Hash then value.to_h { |key, nested| [key.to_s, stringify(nested)] }
+    in Array then value.map { stringify(it) }
+    else value
+    end
+  end
+
+  def deep_sort(value)
+    case value
+    in Hash then value.keys.sort_by(&:to_s).to_h { |key| [key, deep_sort(value[key])] }
+    in Array then value.map { deep_sort(it) }
+    else value
+    end
+  end
+
+  def normalize_paths(path_map)
+    studio = Regexp.union(Html2rss::Web::Routes::ApiV1::FeedRoutes::STUDIO_POSTS.keys).source
+    token_path = %r{\A/api/v1/feeds/(?!(?:#{studio})\z)[^/]+\z}
+    path_map.each_with_object({}) do |(raw, operation), paths|
+      add_operations(paths, normalize_path(raw.to_s, token_path), stringify(operation))
+    end
+  end
+  private_class_method :normalize_paths
+
+  def add_operations(paths, normalized, operations)
+    bucket = paths[normalized] ||= {}
+    operations.each do |verb, doc|
+      bucket[verb] = merge_operation(bucket[verb], doc)
+      decorate_operation(bucket[verb], normalized)
+    end
+  end
+  private_class_method :add_operations
+
+  def normalize_path(original_path, token_path)
+    normalized = if original_path.match?(token_path)
+                   '/feeds/{token}'
+                 elsif original_path.start_with?('/api/v1')
+                   original_path.delete_prefix('/api/v1')
+                 else
+                   original_path
+                 end
+    normalized.empty? ? '/' : normalized
+  end
+  private_class_method :normalize_path
+
+  def merge_operation(existing, operation_doc)
+    return deep_sort(operation_doc) unless existing
+
+    merged = existing.merge(operation_doc)
+    merged['responses'] = merge_responses(existing['responses'] || {}, operation_doc['responses'] || {})
+    merged['parameters'] = [*(existing['parameters'] || []), *(operation_doc['parameters'] || [])]
+    merged['parameters'].uniq! { |parameter| [parameter['name'], parameter['in']] }
+    deep_sort(merged)
+  end
+  private_class_method :merge_operation
+
+  def decorate_operation(doc, normalized)
+    doc['description'] ||= doc['summary']
+    ensure_token_parameter(doc) if normalized.start_with?('/feeds/{token}')
+    inject_retry_after(doc)
+    return unless normalized == '/feeds/{token}'
+
+    overlay_token_feed_content(doc, TOKEN_FEED_ERROR_STATUSES, TOKEN_FEED_ERROR_CONTENT)
+    overlay_token_feed_content(doc, TOKEN_FEED_EMPTY_STATUSES, TOKEN_FEED_EMPTY_CONTENT)
+  end
+  private_class_method :decorate_operation
+
+  def ensure_token_parameter(doc)
+    params = doc['parameters'] ||= []
+    return if params.any? { it['name'] == 'token' && it['in'] == 'path' }
+
+    params << { 'name' => 'token', 'in' => 'path', 'required' => true, 'schema' => { 'type' => 'string' } }
+  end
+  private_class_method :ensure_token_parameter
+
+  def inject_retry_after(doc)
+    RETRY_AFTER_STATUSES.each do |status|
+      response = doc.dig('responses', status)
+      next unless response
+
+      response['headers'] ||= {}
+      response['headers']['Retry-After'] = {
+        'description' => 'The number of seconds to wait before retrying the request.',
+        'schema' => { 'type' => 'integer' }
+      }
+    end
+  end
+  private_class_method :inject_retry_after
+
+  def overlay_token_feed_content(doc, statuses, content)
+    statuses.each do |status|
+      response = doc.dig('responses', status)
+      response['content'] = content if response
+    end
+  end
+  private_class_method :overlay_token_feed_content
+
+  def merge_responses(existing_responses, new_responses)
+    (existing_responses.keys | new_responses.keys).each_with_object({}) do |status, merged|
+      current = existing_responses[status] || {}
+      incoming = new_responses[status] || {}
+      merged[status] = current.merge(incoming).tap do |response|
+        copy_merged_content(response, current, incoming)
+        copy_merged_headers(response, current, incoming)
+        response['description'] = canonical_description(current, incoming)
+      end
+    end
+  end
+  private_class_method :merge_responses
+
+  def copy_merged_content(response, current, incoming)
+    left = Hash(current['content'])
+    right = Hash(incoming['content'])
+    types = left.keys | right.keys
+    return if types.empty?
+
+    response['content'] = types.to_h { |type| [type, left.fetch(type, {}).merge(right.fetch(type, {}))] }
+  end
+  private_class_method :copy_merged_content
+
+  def copy_merged_headers(response, current, incoming)
+    left = Hash(current['headers'])
+    right = Hash(incoming['headers'])
+    return if left.empty? && right.empty?
+
+    response['headers'] = left.merge(right)
+  end
+  private_class_method :copy_merged_headers
+
+  def canonical_description(*responses)
+    descriptions = responses.filter_map { it['description']&.to_s&.strip }.reject(&:empty?).uniq
+    return if descriptions.empty?
+
+    descriptions.min_by { [it.length, it] }
+  end
+  private_class_method :canonical_description
+end

From 6d47063a5ea69b5de23efbc8f42350c895a86bed Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 20 Sep 2026 02:12:33 +0200
Subject: [PATCH 031/108] refactor(frontend): load API metadata through the
 generated client

Replace the hand fetch of GET /api/v1 so the SPA uses the same-origin OpenAPI client and still fail-closes when instance is missing.
---
 .../src/__tests__/apiHttp.metadata.test.ts    | 42 +++++++++++++++++++
 frontend/src/__tests__/mocks/server.ts        |  2 +-
 frontend/src/api/http/metadata.ts             | 17 ++++++++
 frontend/src/hooks/useApiMetadata.ts          | 27 ++----------
 4 files changed, 64 insertions(+), 24 deletions(-)
 create mode 100644 frontend/src/__tests__/apiHttp.metadata.test.ts
 create mode 100644 frontend/src/api/http/metadata.ts

diff --git a/frontend/src/__tests__/apiHttp.metadata.test.ts b/frontend/src/__tests__/apiHttp.metadata.test.ts
new file mode 100644
index 00000000..e85ea8d8
--- /dev/null
+++ b/frontend/src/__tests__/apiHttp.metadata.test.ts
@@ -0,0 +1,42 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { httpRequestUrl } from '../api/http/client';
+import { requestApiMetadata } from '../api/http/metadata';
+
+const metadataBody = {
+  success: true,
+  data: {
+    api: { name: 'html2rss-web API', description: 'd', openapi_url: '/openapi.yaml' },
+    instance: {
+      feed_creation: { enabled: true, access_token_required: true },
+      catalog: { enabled: true, url: '/api/v1/configs' },
+    },
+  },
+};
+
+describe('requestApiMetadata', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('loads GET /api/v1 through the generated client on the same origin', async () => {
+    const fetchMock = vi.spyOn(globalThis, 'fetch').mockResolvedValue(Response.json(metadataBody));
+
+    const payload = await requestApiMetadata();
+    const input = fetchMock.mock.calls[0]?.[0];
+    expect(input).toBeInstanceOf(Request);
+    if (!(input instanceof Request)) return;
+
+    const requested = httpRequestUrl(input);
+    expect(requested.host).not.toBe('api.html2rss.dev');
+    expect(requested.pathname).toMatch(/^\/api\/v1\/?$/);
+    expect(payload?.data.instance.feed_creation.enabled).toBe(true);
+  });
+
+  it('returns undefined when instance is missing', async () => {
+    vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+      Response.json({ success: true, data: { api: metadataBody.data.api } })
+    );
+
+    await expect(requestApiMetadata()).resolves.toBeUndefined();
+  });
+});
diff --git a/frontend/src/__tests__/mocks/server.ts b/frontend/src/__tests__/mocks/server.ts
index 632d098d..9d2a8767 100644
--- a/frontend/src/__tests__/mocks/server.ts
+++ b/frontend/src/__tests__/mocks/server.ts
@@ -2,7 +2,7 @@ import { setupServer } from 'msw/node';
 import { http, HttpResponse } from 'msw';
 
 export const server = setupServer(
-  http.get('/api/v1', () => {
+  http.get(/\/api\/v1\/?$/, () => {
     return HttpResponse.json({
       success: true,
       data: {
diff --git a/frontend/src/api/http/metadata.ts b/frontend/src/api/http/metadata.ts
new file mode 100644
index 00000000..4c1b420c
--- /dev/null
+++ b/frontend/src/api/http/metadata.ts
@@ -0,0 +1,17 @@
+import { getApiMetadata } from '../generated/sdk.gen';
+import type { GetApiMetadataResponse } from '../generated/types.gen';
+import { jsonBaseUrl, unwrap } from './client';
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+export function isApiMetadataResponse(value: unknown): value is GetApiMetadataResponse {
+  return isRecord(value) && value.success === true && isRecord(value.data) && isRecord(value.data.instance);
+}
+
+export async function requestApiMetadata(): Promise<GetApiMetadataResponse | undefined> {
+  const result = await unwrap(getApiMetadata({ baseUrl: jsonBaseUrl() }));
+  if (!result.ok || !isApiMetadataResponse(result.body)) return;
+  return result.body;
+}
diff --git a/frontend/src/hooks/useApiMetadata.ts b/frontend/src/hooks/useApiMetadata.ts
index cc1e53bb..eb045033 100644
--- a/frontend/src/hooks/useApiMetadata.ts
+++ b/frontend/src/hooks/useApiMetadata.ts
@@ -1,5 +1,6 @@
 import { useEffect, useState } from 'preact/hooks';
 import type { ApiMetadataRecord } from '../api/contracts';
+import { requestApiMetadata } from '../api/http/metadata';
 import { COPY } from '../journey/copy';
 
 interface ApiMetadataState {
@@ -8,11 +9,6 @@ interface ApiMetadataState {
   error?: string;
 }
 
-interface ApiMetadataPayload {
-  success?: boolean;
-  data?: unknown;
-}
-
 export function useApiMetadata() {
   const [state, setState] = useState<ApiMetadataState>({
     isLoading: true,
@@ -25,13 +21,9 @@ export function useApiMetadata() {
       setState((previous) => ({ ...previous, isLoading: true, error: undefined }));
 
       try {
-        const response = await fetch('/api/v1', {
-          headers: { Accept: 'application/json' },
-        });
-        const payload = await parseMetadataPayload(response);
-        const metadata = payload.data as ApiMetadataRecord | undefined;
-
-        if (!response.ok || !payload.success || !metadata?.instance) {
+        const payload = await requestApiMetadata();
+        const metadata = payload?.data;
+        if (!metadata?.instance) {
           throw new Error(COPY.instanceUnavailable);
         }
         if (isCancelled) return;
@@ -58,14 +50,3 @@ export function useApiMetadata() {
 
   return state;
 }
-
-async function parseMetadataPayload(response: Response): Promise<ApiMetadataPayload> {
-  const body = await response.text();
-  if (!body.trim()) return {};
-
-  try {
-    return JSON.parse(body) as ApiMetadataPayload;
-  } catch {
-    return {};
-  }
-}

From 9b446900dc5883934495b7a84fd881632c391919 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 20 Sep 2026 02:14:39 +0200
Subject: [PATCH 032/108] refactor(frontend): load the config catalog through
 the generated client

Fetch GET /configs via the same-origin SDK when the catalog flag is on, and keep parseCatalog fail-closed instead of following catalog.url.
---
 .../src/__tests__/apiHttp.catalog.test.ts     | 37 +++++++++++++++++++
 frontend/src/__tests__/useSession.test.ts     |  5 ++-
 frontend/src/api/http/catalog.ts              |  8 ++++
 frontend/src/catalog/useCatalogEntries.ts     | 15 +++-----
 4 files changed, 53 insertions(+), 12 deletions(-)
 create mode 100644 frontend/src/__tests__/apiHttp.catalog.test.ts
 create mode 100644 frontend/src/api/http/catalog.ts

diff --git a/frontend/src/__tests__/apiHttp.catalog.test.ts b/frontend/src/__tests__/apiHttp.catalog.test.ts
new file mode 100644
index 00000000..a6eb2f4f
--- /dev/null
+++ b/frontend/src/__tests__/apiHttp.catalog.test.ts
@@ -0,0 +1,37 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { httpRequestUrl } from '../api/http/client';
+import { requestConfigCatalog } from '../api/http/catalog';
+
+const catalogBody = {
+  success: true,
+  data: { configs: [] },
+  meta: { total: 0, catalog_version: 2, starters: [] },
+};
+
+describe('requestConfigCatalog', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('loads GET /configs through the generated client and ignores catalog.url', async () => {
+    const fetchMock = vi.spyOn(globalThis, 'fetch').mockResolvedValue(Response.json(catalogBody));
+
+    const payload = await requestConfigCatalog();
+    const input = fetchMock.mock.calls[0]?.[0];
+    expect(input).toBeInstanceOf(Request);
+    if (!(input instanceof Request)) return;
+
+    const requested = httpRequestUrl(input);
+    expect(requested.host).not.toBe('api.html2rss.dev');
+    expect(requested.pathname).toBe('/api/v1/configs');
+    expect(payload).toMatchObject({ success: true, meta: { catalog_version: 2 } });
+  });
+
+  it('returns undefined when the catalog is disabled', async () => {
+    vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+      Response.json({ error: 'catalog_disabled' }, { status: 404 })
+    );
+
+    await expect(requestConfigCatalog()).resolves.toBeUndefined();
+  });
+});
diff --git a/frontend/src/__tests__/useSession.test.ts b/frontend/src/__tests__/useSession.test.ts
index f900f96f..17e33793 100644
--- a/frontend/src/__tests__/useSession.test.ts
+++ b/frontend/src/__tests__/useSession.test.ts
@@ -1,5 +1,6 @@
 import { describe, it, expect, beforeEach, afterEach, vi, type SpyInstance } from 'vitest';
 import { renderHook, act, waitFor } from '@testing-library/preact';
+import { httpRequestUrl } from '../api/http/client';
 import { resetAccessTokenMemory, useSession } from '../session';
 import { getPersistentStorage } from '../utils/persistentStorage';
 
@@ -24,8 +25,8 @@ describe('useSession', () => {
 
   const mockFetchFor = (metadata: unknown, catalogResponse: Response = emptyCatalogResponse) => {
     fetchMock.mockImplementation(async (input: RequestInfo | URL) => {
-      const url = String(input);
-      if (url.includes('/configs')) return catalogResponse.clone();
+      const url = httpRequestUrl(input);
+      if (url.pathname.includes('/configs')) return catalogResponse.clone();
       return Response.json({ success: true, data: metadata });
     });
   };
diff --git a/frontend/src/api/http/catalog.ts b/frontend/src/api/http/catalog.ts
new file mode 100644
index 00000000..fc95d13a
--- /dev/null
+++ b/frontend/src/api/http/catalog.ts
@@ -0,0 +1,8 @@
+import { getConfigCatalog } from '../generated/sdk.gen';
+import { jsonBaseUrl, unwrap } from './client';
+
+export async function requestConfigCatalog(): Promise<unknown> {
+  const result = await unwrap(getConfigCatalog({ baseUrl: jsonBaseUrl() }));
+  if (!result.ok) return;
+  return result.body;
+}
diff --git a/frontend/src/catalog/useCatalogEntries.ts b/frontend/src/catalog/useCatalogEntries.ts
index 0f84b236..3fc3d7cf 100644
--- a/frontend/src/catalog/useCatalogEntries.ts
+++ b/frontend/src/catalog/useCatalogEntries.ts
@@ -1,5 +1,6 @@
 import { useEffect, useState } from 'preact/hooks';
 import type { ApiMetadataRecord } from '../api/contracts';
+import { requestConfigCatalog } from '../api/http/catalog';
 import { parseCatalog } from './parseCatalog';
 import type { CatalogEntry } from './types';
 
@@ -15,10 +16,10 @@ const EMPTY: CatalogHookState = { entries: [], starters: [] };
  */
 export function useCatalogEntries(metadata?: ApiMetadataRecord): CatalogHookState {
   const [snapshot, setSnapshot] = useState<CatalogHookState>(EMPTY);
-  const catalog = metadata?.instance.catalog;
+  const isCatalogEnabled = metadata?.instance.catalog?.enabled === true;
 
   useEffect(() => {
-    if (!catalog?.enabled || !catalog.url) {
+    if (!isCatalogEnabled) {
       setSnapshot(EMPTY);
       return;
     }
@@ -27,13 +28,7 @@ export function useCatalogEntries(metadata?: ApiMetadataRecord): CatalogHookStat
 
     const load = async () => {
       try {
-        const response = await fetch(catalog.url, { headers: { Accept: 'application/json' } });
-        if (!response.ok) {
-          if (!isCancelled) setSnapshot(EMPTY);
-          return;
-        }
-
-        const payload: unknown = await response.json();
+        const payload = await requestConfigCatalog();
         if (isCancelled) return;
         const parsed = parseCatalog(payload);
         setSnapshot({ entries: parsed.entries, starters: parsed.starters });
@@ -46,7 +41,7 @@ export function useCatalogEntries(metadata?: ApiMetadataRecord): CatalogHookStat
     return () => {
       isCancelled = true;
     };
-  }, [catalog?.enabled, catalog?.url]);
+  }, [isCatalogEnabled]);
 
   return snapshot;
 }

From f37042bf34608b741c23c7d9f91845a28c903d1b Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 20 Sep 2026 02:20:31 +0200
Subject: [PATCH 033/108] refactor(frontend): create feeds through the
 generated client

Route create, validate, preview, and suggest JSON posts through the same-origin adapter so UI never value-imports the SDK, while json_public_url preview stays a hand fetch.
---
 frontend/src/__tests__/App.contract.test.tsx  |   9 +-
 frontend/src/__tests__/apiHttp.feeds.test.ts  |  91 ++++++++++++++++
 .../useFeedCreation.contract.test.ts          |   9 +-
 .../src/__tests__/useFeedCreation.test.ts     |  36 +++++--
 frontend/src/__tests__/useStudio.test.ts      | 102 ++++++++++--------
 frontend/src/api/http/feeds.ts                |  99 +++++++++++++++++
 frontend/src/feeds/feedsService.ts            |  56 ++++------
 frontend/src/studio/studioService.ts          |  45 ++------
 8 files changed, 320 insertions(+), 127 deletions(-)
 create mode 100644 frontend/src/__tests__/apiHttp.feeds.test.ts
 create mode 100644 frontend/src/api/http/feeds.ts

diff --git a/frontend/src/__tests__/App.contract.test.tsx b/frontend/src/__tests__/App.contract.test.tsx
index 4a6ff197..a4cdb8b8 100644
--- a/frontend/src/__tests__/App.contract.test.tsx
+++ b/frontend/src/__tests__/App.contract.test.tsx
@@ -1,10 +1,15 @@
 import { describe, it, expect, beforeEach, vi } from 'vitest';
 import { render, screen, fireEvent, waitFor } from '@testing-library/preact';
 import { http, HttpResponse } from 'msw';
+import { httpRequestUrl } from '../api/http/client';
 import { server, buildFeedResponse, buildStructuredErrorResponse } from './mocks/server';
 import { App } from '../components/App';
 import { COPY } from '../journey/copy';
 
+function isGeneratedPreview(input: RequestInfo | URL): boolean {
+  return httpRequestUrl(input).pathname.endsWith('/api/v1/feeds/generated-token.json');
+}
+
 describe('App contract', () => {
   const token = 'contract-token';
 
@@ -18,7 +23,7 @@ describe('App contract', () => {
   it('shows feed result when the API returns structured create payload and preview feed', async () => {
     const nativeFetch = fetch;
     const fetchSpy = vi.spyOn(globalThis, 'fetch').mockImplementation((input, init) => {
-      if (String(input).endsWith('/api/v1/feeds/generated-token.json')) {
+      if (isGeneratedPreview(input)) {
         expect((init?.headers as Record<string, string> | undefined)?.Accept).toBe('application/feed+json');
         return Promise.resolve(
           Response.json(
@@ -154,7 +159,7 @@ describe('App contract', () => {
   it('posts refined selectors from the studio and returns to the result view', async () => {
     const nativeFetch = fetch;
     const fetchSpy = vi.spyOn(globalThis, 'fetch').mockImplementation((input, init) => {
-      if (String(input).endsWith('/api/v1/feeds/generated-token.json')) {
+      if (isGeneratedPreview(input)) {
         return Promise.resolve(
           Response.json(
             {
diff --git a/frontend/src/__tests__/apiHttp.feeds.test.ts b/frontend/src/__tests__/apiHttp.feeds.test.ts
new file mode 100644
index 00000000..28b72677
--- /dev/null
+++ b/frontend/src/__tests__/apiHttp.feeds.test.ts
@@ -0,0 +1,91 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { httpRequestUrl } from '../api/http/client';
+import { postCreateFeed, postPreviewFeed, postSuggestSelectors, postValidateFeed } from '../api/http/feeds';
+
+const createdFeed = {
+  success: true,
+  data: {
+    feed: {
+      id: 'feed-1',
+      name: 'Example',
+      url: 'https://example.com',
+      feed_token: 'tok',
+      public_url: '/api/v1/feeds/tok',
+      json_public_url: '/api/v1/feeds/tok.json',
+    },
+  },
+};
+
+describe('postCreateFeed', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('POSTs /feeds on the same origin and omits Authorization when the token is empty', async () => {
+    const fetchMock = vi
+      .spyOn(globalThis, 'fetch')
+      .mockResolvedValue(Response.json({ success: false, error: { code: 'UNAUTHORIZED' } }, { status: 401 }));
+
+    const envelope = await postCreateFeed('https://example.com', '  ');
+    const input = fetchMock.mock.calls[0]?.[0];
+    expect(input).toBeInstanceOf(Request);
+    if (!(input instanceof Request)) return;
+
+    const requested = httpRequestUrl(input);
+    expect(requested.host).not.toBe('api.html2rss.dev');
+    expect(requested.pathname).toBe('/api/v1/feeds');
+    expect(input.method).toBe('POST');
+    expect(input.headers.get('Authorization')).toBeNull();
+    expect(JSON.parse(await input.clone().text())).toEqual({ url: 'https://example.com' });
+    expect(envelope).toMatchObject({ ok: false, status: 401 });
+  });
+
+  it('sends Bearer auth and optional selectors through the generated client', async () => {
+    const fetchMock = vi
+      .spyOn(globalThis, 'fetch')
+      .mockResolvedValue(Response.json(createdFeed, { status: 201 }));
+    const selectors = { items: { selector: 'article', enhance: false }, title: { selector: 'h2' } };
+
+    const envelope = await postCreateFeed('https://example.com/articles', 'token-123', selectors);
+    const input = fetchMock.mock.calls[0]?.[0];
+    expect(input).toBeInstanceOf(Request);
+    if (!(input instanceof Request)) return;
+
+    expect(httpRequestUrl(input).host).not.toBe('api.html2rss.dev');
+    expect(input.headers.get('Authorization')).toBe('Bearer token-123');
+    expect(JSON.parse(await input.clone().text())).toEqual({
+      url: 'https://example.com/articles',
+      selectors,
+    });
+    expect(envelope).toMatchObject({ ok: true, status: 201 });
+  });
+});
+
+describe('studio JSON writes', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('POSTs validate, preview, and suggest through the generated client', async () => {
+    const fetchMock = vi.spyOn(globalThis, 'fetch').mockResolvedValue(Response.json({ success: true }));
+    const selectors = { items: { selector: 'article', enhance: false } };
+
+    await postValidateFeed('token-123', selectors);
+    await postPreviewFeed('token-123', 'https://example.com', selectors);
+    await postSuggestSelectors('token-123', 'https://example.com', 'article');
+
+    const paths = fetchMock.mock.calls.map((call) => {
+      const input = call[0];
+      expect(input).toBeInstanceOf(Request);
+      if (!(input instanceof Request)) return '';
+      expect(httpRequestUrl(input).host).not.toBe('api.html2rss.dev');
+      return httpRequestUrl(input).pathname;
+    });
+
+    expect(paths).toEqual([
+      '/api/v1/feeds/validate',
+      '/api/v1/feeds/preview',
+      '/api/v1/feeds/suggest_selectors',
+    ]);
+  });
+});
diff --git a/frontend/src/__tests__/useFeedCreation.contract.test.ts b/frontend/src/__tests__/useFeedCreation.contract.test.ts
index 69f4ca4e..070a10d6 100644
--- a/frontend/src/__tests__/useFeedCreation.contract.test.ts
+++ b/frontend/src/__tests__/useFeedCreation.contract.test.ts
@@ -1,15 +1,20 @@
 import { describe, it, expect, vi } from 'vitest';
 import { renderHook, act, waitFor } from '@testing-library/preact';
 import { http, HttpResponse } from 'msw';
+import { httpRequestUrl } from '../api/http/client';
 import { server, buildFeedResponse, buildStructuredErrorResponse } from './mocks/server';
 import { useFeedCreation } from '../feed';
 
+function isGeneratedPreview(input: RequestInfo | URL): boolean {
+  return httpRequestUrl(input).pathname.endsWith('/api/v1/feeds/generated-token.json');
+}
+
 describe('useFeedCreation contract', () => {
   it('sends feed creation requests with bearer auth and hydrates preview from json_public_url', async () => {
     let receivedAuthorization: string | undefined;
     const nativeFetch = fetch;
     const fetchSpy = vi.spyOn(globalThis, 'fetch').mockImplementation((input, init) => {
-      if (String(input).endsWith('/api/v1/feeds/generated-token.json')) {
+      if (isGeneratedPreview(input)) {
         return Promise.resolve(
           Response.json(
             { items: [{ title: 'Preview', content_text: 'Text' }] },
@@ -135,7 +140,7 @@ describe('useFeedCreation contract', () => {
   it('marks preview failure from the feed json response without status polling', async () => {
     const nativeFetch = fetch;
     const fetchSpy = vi.spyOn(globalThis, 'fetch').mockImplementation((input, init) => {
-      if (String(input).endsWith('/api/v1/feeds/generated-token.json')) {
+      if (isGeneratedPreview(input)) {
         return Promise.resolve(new Response('No feed items', { status: 422 }));
       }
 
diff --git a/frontend/src/__tests__/useFeedCreation.test.ts b/frontend/src/__tests__/useFeedCreation.test.ts
index 6a997408..9f45a115 100644
--- a/frontend/src/__tests__/useFeedCreation.test.ts
+++ b/frontend/src/__tests__/useFeedCreation.test.ts
@@ -1,7 +1,24 @@
 import { describe, it, expect, beforeEach, afterEach, vi, type SpyInstance } from 'vitest';
 import { renderHook, act, waitFor } from '@testing-library/preact';
+import { httpRequestUrl } from '../api/http/client';
 import { useFeedCreation } from '../feed';
 
+function fetchInput(call: unknown[] | undefined): RequestInfo | URL | undefined {
+  const input = call?.[0];
+  if (typeof input === 'string' || input instanceof URL || input instanceof Request) return input;
+  return;
+}
+
+function isCreateFeedCall(call: unknown[] | undefined): boolean {
+  const input = fetchInput(call);
+  return input !== undefined && httpRequestUrl(input).pathname === '/api/v1/feeds';
+}
+
+function isJsonPreviewCall(call: unknown[] | undefined): boolean {
+  const input = fetchInput(call);
+  return input !== undefined && httpRequestUrl(input).pathname.endsWith('/api/v1/feeds/feed-token-1.json');
+}
+
 const mockFeed = {
   id: 'feed-1',
   name: 'Example Feed',
@@ -54,8 +71,14 @@ describe('useFeedCreation', () => {
       await result.current.createFeed('https://example.com/articles', 'token-123');
     });
 
-    expect(fetchMock.mock.calls[0]?.[0]).toBe('/api/v1/feeds');
-    expect(String(fetchMock.mock.calls[1]?.[0])).toMatch(/\/api\/v1\/feeds\/feed-token-1\.json$/);
+    const createInput = fetchInput(fetchMock.mock.calls[0]);
+    expect(createInput).toBeDefined();
+    if (!createInput) return;
+    expect(httpRequestUrl(createInput).pathname).toBe('/api/v1/feeds');
+    const previewInput = fetchInput(fetchMock.mock.calls[1]);
+    expect(previewInput).toBeDefined();
+    if (!previewInput) return;
+    expect(httpRequestUrl(previewInput).pathname).toMatch(/\/api\/v1\/feeds\/feed-token-1\.json$/);
     expect(fetchMock.mock.calls).toHaveLength(2);
 
     await waitFor(() => {
@@ -83,11 +106,8 @@ describe('useFeedCreation', () => {
     await waitFor(() => {
       expect(result.current.result?.preview.status).toBe('preview_ready');
     });
-    expect(fetchMock.mock.calls.filter((call) => String(call[0]) === '/api/v1/feeds').length).toBe(1);
-    expect(
-      fetchMock.mock.calls.filter((call) => String(call[0]).endsWith('/api/v1/feeds/feed-token-1.json'))
-        .length
-    ).toBe(2);
+    expect(fetchMock.mock.calls.filter((call) => isCreateFeedCall(call)).length).toBe(1);
+    expect(fetchMock.mock.calls.filter((call) => isJsonPreviewCall(call)).length).toBe(2);
 
     vi.useRealTimers();
   });
@@ -127,6 +147,6 @@ describe('useFeedCreation', () => {
     act(() => result.current.retryPreviewFetch());
 
     await waitFor(() => expect(result.current.result?.preview.status).toBe('preview_ready'));
-    expect(fetchMock.mock.calls.filter((call) => String(call[0]) === '/api/v1/feeds').length).toBe(1);
+    expect(fetchMock.mock.calls.filter((call) => isCreateFeedCall(call)).length).toBe(1);
   });
 });
diff --git a/frontend/src/__tests__/useStudio.test.ts b/frontend/src/__tests__/useStudio.test.ts
index 5e7b3f01..2d3ef07b 100644
--- a/frontend/src/__tests__/useStudio.test.ts
+++ b/frontend/src/__tests__/useStudio.test.ts
@@ -7,11 +7,28 @@ import {
   withFieldSelector,
 } from '../studio/selectorDraft';
 import { STUDIO_PREVIEW_SETTLE_MS, STUDIO_VALIDATE_DELAY_MS, useStudio } from '../studio/useStudio';
+import { httpRequestUrl } from '../api/http/client';
 
 const pageUrl = 'https://example.com/articles';
 const token = 'studio-token';
 const wireNull: unknown = JSON.parse('null');
 
+function fetchPath(input: RequestInfo | URL): string {
+  return httpRequestUrl(input).pathname;
+}
+
+async function fetchJsonBody(input: RequestInfo | URL, init?: RequestInit): Promise<unknown> {
+  if (input instanceof Request) {
+    const text = await input.clone().text();
+    return text.trim() ? JSON.parse(text) : undefined;
+  }
+  return typeof init?.body === 'string' && init.body.trim() ? JSON.parse(init.body) : undefined;
+}
+
+function selectorsFromBody(parsed: unknown): unknown {
+  return typeof parsed === 'object' && parsed && 'selectors' in parsed ? parsed.selectors : undefined;
+}
+
 function validateBody(overrides: Record<string, unknown> = {}) {
   return {
     success: true,
@@ -37,7 +54,11 @@ function suggestionBody(isEnhanced = false, selector = 'article') {
 }
 
 function callsTo(fetchMock: SpyInstance, suffix: string) {
-  return fetchMock.mock.calls.filter((call) => String(call[0]).endsWith(suffix));
+  return fetchMock.mock.calls.filter((call) => {
+    const input = call[0];
+    if (input === undefined) return false;
+    return fetchPath(input).endsWith(suffix);
+  });
 }
 
 describe('selector draft', () => {
@@ -101,7 +122,7 @@ describe('useStudio', () => {
   it('waits 300ms, sends the bearer token, and unwraps a valid report', async () => {
     vi.useFakeTimers();
     fetchMock.mockImplementation((input: RequestInfo | URL) => {
-      if (String(input).endsWith('/feeds/suggest_selectors')) {
+      if (fetchPath(input).endsWith('/feeds/suggest_selectors')) {
         return Promise.resolve(Response.json(suggestionBody(false)));
       }
       return Promise.resolve(Response.json(validateBody()));
@@ -127,10 +148,12 @@ describe('useStudio', () => {
 
     const validateCalls = callsTo(fetchMock, '/feeds/validate');
     expect(validateCalls).toHaveLength(1);
-    expect(validateCalls[0]?.[0]).toBe('/api/v1/feeds/validate');
-    const init = validateCalls[0]?.[1];
-    expect(init?.headers).toMatchObject({ Authorization: `Bearer ${token}` });
-    expect(JSON.parse(String(init?.body))).toEqual({
+    const validateInput = validateCalls[0]?.[0];
+    expect(validateInput).toBeInstanceOf(Request);
+    if (!(validateInput instanceof Request)) return;
+    expect(fetchPath(validateInput)).toBe('/api/v1/feeds/validate');
+    expect(validateInput.headers.get('Authorization')).toBe(`Bearer ${token}`);
+    expect(JSON.parse(await validateInput.clone().text())).toEqual({
       selectors: { items: { selector: 'article', enhance: false } },
     });
 
@@ -146,7 +169,7 @@ describe('useStudio', () => {
   it('keeps returned issue codes on the invalid phase and does not preview', async () => {
     vi.useFakeTimers();
     fetchMock.mockImplementation((input: RequestInfo | URL) => {
-      if (String(input).endsWith('/feeds/suggest_selectors')) {
+      if (fetchPath(input).endsWith('/feeds/suggest_selectors')) {
         return Promise.resolve(Response.json(suggestionBody(false)));
       }
       return Promise.resolve(
@@ -194,7 +217,7 @@ describe('useStudio', () => {
   it('previews only after validation succeeds and the settle delay', async () => {
     vi.useFakeTimers();
     fetchMock.mockImplementation((input: RequestInfo | URL) => {
-      const path = String(input);
+      const path = fetchPath(input);
       if (path.endsWith('/feeds/suggest_selectors')) {
         return Promise.resolve(Response.json(suggestionBody(false)));
       }
@@ -265,10 +288,10 @@ describe('useStudio', () => {
 
   it('fills an empty items selector once from suggestion and does not repeat', async () => {
     fetchMock.mockImplementation(async (input: RequestInfo | URL, init?: RequestInit) => {
-      if (String(input).endsWith('/feeds/suggest_selectors')) {
+      if (fetchPath(input).endsWith('/feeds/suggest_selectors')) {
         return Response.json(suggestionBody(true, '.post'));
       }
-      if (String(input).endsWith('/feeds/preview')) {
+      if (fetchPath(input).endsWith('/feeds/preview')) {
         return Response.json({
           success: true,
           data: {
@@ -281,9 +304,8 @@ describe('useStudio', () => {
         });
       }
 
-      const parsed: unknown = JSON.parse(String(init?.body));
-      const selectors =
-        typeof parsed === 'object' && parsed && 'selectors' in parsed ? parsed.selectors : undefined;
+      const parsed = await fetchJsonBody(input, init);
+      const selectors = selectorsFromBody(parsed);
       return Response.json(
         validateBody({
           selectors: selectors ?? { items: { selector: '', enhance: false } },
@@ -303,34 +325,29 @@ describe('useStudio', () => {
 
   it('does not overwrite an items selector the user already typed', async () => {
     const pendingSuggestion = Promise.withResolvers<Response>();
-    fetchMock.mockImplementation((input: RequestInfo | URL, init?: RequestInit) => {
-      if (String(input).endsWith('/feeds/suggest_selectors')) {
+    fetchMock.mockImplementation(async (input: RequestInfo | URL, init?: RequestInit) => {
+      if (fetchPath(input).endsWith('/feeds/suggest_selectors')) {
         return pendingSuggestion.promise;
       }
-      if (String(input).endsWith('/feeds/preview')) {
-        return Promise.resolve(
-          Response.json({
-            success: true,
-            data: {
-              item_count: 0,
-              sample_items: [],
-              quality_report: wireNull,
-              failure_kind: wireNull,
-              validation_issues: [],
-            },
-          })
-        );
+      if (fetchPath(input).endsWith('/feeds/preview')) {
+        return Response.json({
+          success: true,
+          data: {
+            item_count: 0,
+            sample_items: [],
+            quality_report: wireNull,
+            failure_kind: wireNull,
+            validation_issues: [],
+          },
+        });
       }
 
-      const parsed: unknown = JSON.parse(String(init?.body));
-      const selectors =
-        typeof parsed === 'object' && parsed && 'selectors' in parsed ? parsed.selectors : undefined;
-      return Promise.resolve(
-        Response.json(
-          validateBody({
-            selectors: selectors ?? { items: { selector: 'article', enhance: false } },
-          })
-        )
+      const parsed = await fetchJsonBody(input, init);
+      const selectors = selectorsFromBody(parsed);
+      return Response.json(
+        validateBody({
+          selectors: selectors ?? { items: { selector: 'article', enhance: false } },
+        })
       );
     });
 
@@ -353,7 +370,7 @@ describe('useStudio', () => {
 
   it('keeps an http image url from the preview sample and drops anything else', async () => {
     fetchMock.mockImplementation((input: RequestInfo | URL) => {
-      const path = String(input);
+      const path = fetchPath(input);
       if (path.endsWith('/feeds/suggest_selectors')) {
         return Promise.resolve(Response.json(suggestionBody(false)));
       }
@@ -395,10 +412,10 @@ describe('useStudio', () => {
 
   it('applies one capture suggestion onto the items selector', async () => {
     fetchMock.mockImplementation(async (input: RequestInfo | URL, init?: RequestInit) => {
-      if (String(input).endsWith('/feeds/suggest_selectors')) {
+      if (fetchPath(input).endsWith('/feeds/suggest_selectors')) {
         return Response.json(suggestionBody(true, '.post'));
       }
-      if (String(input).endsWith('/feeds/preview')) {
+      if (fetchPath(input).endsWith('/feeds/preview')) {
         return Response.json({
           success: true,
           data: {
@@ -411,9 +428,8 @@ describe('useStudio', () => {
         });
       }
 
-      const parsed: unknown = JSON.parse(String(init?.body));
-      const selectors =
-        typeof parsed === 'object' && parsed && 'selectors' in parsed ? parsed.selectors : undefined;
+      const parsed = await fetchJsonBody(input, init);
+      const selectors = selectorsFromBody(parsed);
       return Response.json(
         validateBody({
           selectors: selectors ?? { items: { selector: 'article', enhance: false } },
diff --git a/frontend/src/api/http/feeds.ts b/frontend/src/api/http/feeds.ts
new file mode 100644
index 00000000..b2199cfc
--- /dev/null
+++ b/frontend/src/api/http/feeds.ts
@@ -0,0 +1,99 @@
+import { client } from '../generated/client.gen';
+import type {
+  CreateFeedData,
+  PreviewFeedData,
+  SuggestSelectorsData,
+  ValidateFeedConfigData,
+} from '../generated/types.gen';
+import { isAbortError } from '../../feeds/feedPreviewClient';
+import { jsonBaseUrl, unwrap, type HttpEnvelope } from './client';
+
+type CreateFeedWrite = Omit<NonNullable<CreateFeedData['body']>, 'selectors'> & {
+  readonly selectors?: Record<string, unknown>;
+};
+
+type PreviewFeedWrite = Omit<NonNullable<PreviewFeedData['body']>, 'selectors'> & {
+  readonly selectors: Record<string, unknown>;
+};
+
+type SuggestSelectorsWrite = NonNullable<SuggestSelectorsData['body']>;
+
+type ValidateFeedWrite = Omit<NonNullable<ValidateFeedConfigData['body']>, 'selectors'> & {
+  readonly selectors: Record<string, unknown>;
+};
+
+const FEED_WRITE_URL = {
+  create: '/feeds',
+  preview: '/feeds/preview',
+  suggest: '/feeds/suggest_selectors',
+  validate: '/feeds/validate',
+} as const satisfies {
+  create: CreateFeedData['url'];
+  preview: PreviewFeedData['url'];
+  suggest: SuggestSelectorsData['url'];
+  validate: ValidateFeedConfigData['url'];
+};
+
+function bearerAuth(token: string): string | undefined {
+  const trimmed = token.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+async function jsonWrite(
+  url: (typeof FEED_WRITE_URL)[keyof typeof FEED_WRITE_URL],
+  token: string,
+  body: unknown,
+  signal?: AbortSignal
+): Promise<HttpEnvelope> {
+  const envelope = await unwrap(
+    client.post({
+      url,
+      baseUrl: jsonBaseUrl(),
+      body,
+      auth: bearerAuth(token),
+      security: [{ scheme: 'bearer', type: 'http' }],
+      headers: { 'Content-Type': 'application/json' },
+      signal,
+    })
+  );
+  if (isAbortError(envelope.body)) throw envelope.body;
+  return envelope;
+}
+
+export function postCreateFeed(
+  url: string,
+  token: string,
+  selectors?: Record<string, unknown>
+): Promise<HttpEnvelope> {
+  const body: CreateFeedWrite = selectors ? { url, selectors } : { url };
+  return jsonWrite(FEED_WRITE_URL.create, token, body);
+}
+
+export function postValidateFeed(
+  token: string,
+  selectors: Record<string, unknown>,
+  signal?: AbortSignal
+): Promise<HttpEnvelope> {
+  const body: ValidateFeedWrite = { selectors };
+  return jsonWrite(FEED_WRITE_URL.validate, token, body, signal);
+}
+
+export function postPreviewFeed(
+  token: string,
+  url: string,
+  selectors: Record<string, unknown>,
+  signal?: AbortSignal
+): Promise<HttpEnvelope> {
+  const body: PreviewFeedWrite = { url, selectors };
+  return jsonWrite(FEED_WRITE_URL.preview, token, body, signal);
+}
+
+export function postSuggestSelectors(
+  token: string,
+  url: string,
+  itemsSelector: string,
+  signal?: AbortSignal
+): Promise<HttpEnvelope> {
+  const body: SuggestSelectorsWrite = { url, items_selector: itemsSelector };
+  return jsonWrite(FEED_WRITE_URL.suggest, token, body, signal);
+}
diff --git a/frontend/src/feeds/feedsService.ts b/frontend/src/feeds/feedsService.ts
index a6cae969..f092b2a6 100644
--- a/frontend/src/feeds/feedsService.ts
+++ b/frontend/src/feeds/feedsService.ts
@@ -1,4 +1,5 @@
 import type { FeedRecord } from '../api/contracts';
+import { postCreateFeed } from '../api/http/feeds';
 import { COPY } from '../journey/copy';
 import {
   buildStructuredError,
@@ -6,7 +7,6 @@ import {
   type RawApiResponse,
 } from './feedErrors';
 import { normalizeString } from './feedParsers';
-import { readJsonResponse } from './feedPreviewClient';
 
 export * from './feedErrors';
 export * from './feedParsers';
@@ -23,12 +23,20 @@ interface RawFeedRecord {
   updated_at?: unknown;
 }
 
-interface RawFeedPayload {
-  feed?: RawFeedRecord;
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
 }
 
-interface RawFeedApiResponse extends RawApiResponse {
-  data?: RawFeedPayload;
+function feedApiResponse(body: unknown): RawApiResponse | undefined {
+  if (!isRecord(body)) return;
+  return { success: body.success, data: body.data, error: body.error };
+}
+
+function rawFeedRecord(body: unknown): RawFeedRecord | undefined {
+  const payload = feedApiResponse(body);
+  if (!isRecord(payload?.data)) return;
+  const feed = payload.data.feed;
+  return isRecord(feed) ? feed : undefined;
 }
 
 export async function requestFeedCreation(
@@ -36,22 +44,14 @@ export async function requestFeedCreation(
   token: string,
   selectors?: Record<string, unknown>
 ): Promise<FeedRecord> {
-  const body: { url: string; selectors?: Record<string, unknown> } = { url };
-  if (selectors) body.selectors = selectors;
-
-  const response = await fetch(resolveApiUrl('feeds'), {
-    method: 'POST',
-    headers: buildCreateHeaders(token),
-    body: JSON.stringify(body),
-  });
+  const envelope = await postCreateFeed(url, token, selectors);
+  const payload = feedApiResponse(envelope.body);
 
-  const payload = await readJsonResponse<RawFeedApiResponse>(response);
-
-  if (!response.ok) {
-    throw normalizeFeedCreationErrorFromResponse(response.status, payload?.error, payload);
+  if (!envelope.ok) {
+    throw normalizeFeedCreationErrorFromResponse(envelope.status, payload?.error, payload);
   }
 
-  const feed = normalizeFeedRecord(payload?.data?.feed);
+  const feed = normalizeFeedRecord(rawFeedRecord(envelope.body));
   if (!feed) {
     throw buildStructuredError(
       'server',
@@ -60,7 +60,7 @@ export async function requestFeedCreation(
       'retry',
       'primary',
       COPY.unableToStartCreation,
-      response.status
+      envelope.status
     );
   }
 
@@ -88,21 +88,3 @@ export function normalizeFeedRecord(raw?: RawFeedRecord): FeedRecord | undefined
     updated_at: normalizeString(raw.updated_at) || new Date().toISOString(),
   };
 }
-
-export function resolveApiUrl(path: string): string {
-  return `/api/v1/${path.replace(/^\/+/, '')}`;
-}
-
-export function buildCreateHeaders(token: string): HeadersInit {
-  const normalizedToken = token.trim();
-  const headers: Record<string, string> = {
-    Accept: 'application/json',
-    'Content-Type': 'application/json',
-  };
-
-  if (normalizedToken) {
-    headers.Authorization = `Bearer ${normalizedToken}`;
-  }
-
-  return headers;
-}
diff --git a/frontend/src/studio/studioService.ts b/frontend/src/studio/studioService.ts
index 795df818..7a296b4f 100644
--- a/frontend/src/studio/studioService.ts
+++ b/frontend/src/studio/studioService.ts
@@ -6,8 +6,10 @@
  * example shape (`items` only), not the allowlisted subtree.
  */
 import type { ValidateFeedConfigResponses } from '../api/generated';
+import type { HttpEnvelope } from '../api/http/client';
+import { postPreviewFeed, postSuggestSelectors, postValidateFeed } from '../api/http/feeds';
+import { isAbortError } from '../feeds/feedsService';
 import { COPY } from '../journey/copy';
-import { buildCreateHeaders, isAbortError, resolveApiUrl } from '../feeds/feedsService';
 import { draftFromSelectors, isPlainRecord, selectorsFromDraft, type StudioDraft } from './selectorDraft';
 
 type GeneratedIssue = ValidateFeedConfigResponses[200]['data']['report']['issues'][number];
@@ -81,7 +83,7 @@ export async function previewStudioFeed(
   draft: StudioDraft,
   signal?: AbortSignal
 ): Promise<StudioPreview> {
-  const data = await postJson('feeds/preview', token, { url, selectors: selectorsFromDraft(draft) }, signal);
+  const data = await studioData(await postPreviewFeed(token, url, selectorsFromDraft(draft), signal));
   return parsePreview(data);
 }
 
@@ -91,12 +93,7 @@ export async function suggestStudioSelectors(
   itemsSelector: string,
   signal?: AbortSignal
 ): Promise<StudioSuggestion> {
-  const data = await postJson(
-    'feeds/suggest_selectors',
-    token,
-    { url, items_selector: itemsSelector },
-    signal
-  );
+  const data = await studioData(await postSuggestSelectors(token, url, itemsSelector, signal));
   return parseSuggestion(data);
 }
 
@@ -105,41 +102,19 @@ async function validateStudio(
   selectors: Record<string, unknown>,
   signal?: AbortSignal
 ): Promise<StudioValidationOutcome> {
-  return parseValidation(await postJson('feeds/validate', token, { selectors }, signal));
+  return parseValidation(await studioData(await postValidateFeed(token, selectors, signal)));
 }
 
-async function postJson(path: string, token: string, body: unknown, signal?: AbortSignal): Promise<unknown> {
-  let response: Response;
-  try {
-    response = await fetch(resolveApiUrl(path), {
-      method: 'POST',
-      headers: buildCreateHeaders(token),
-      body: JSON.stringify(body),
-      signal,
-    });
-  } catch (error) {
-    if (isAbortError(error)) throw error;
-    throw new StudioRequestError(COPY.unableToReachServer);
-  }
-
-  const payload = await readPayload(response);
-  if (!response.ok || !isPlainRecord(payload) || payload.success !== true) {
+async function studioData(envelope: HttpEnvelope): Promise<unknown> {
+  const payload = envelope.body;
+  if (isAbortError(payload)) throw payload;
+  if (!envelope.ok || !isPlainRecord(payload) || payload.success !== true) {
     throw new StudioRequestError(errorMessage(payload) ?? COPY.unableToCompleteCreation);
   }
 
   return payload.data;
 }
 
-async function readPayload(response: Response): Promise<unknown> {
-  const text = await response.text();
-  if (!text.trim()) return;
-  try {
-    return JSON.parse(text);
-  } catch {
-    return;
-  }
-}
-
 function errorMessage(payload: unknown): string | undefined {
   if (!isPlainRecord(payload) || !isPlainRecord(payload.error)) return;
   const message = payload.error.message;

From 083fda79b6edd37e63de98647908947b959daf51 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 20 Sep 2026 02:24:01 +0200
Subject: [PATCH 034/108] docs: treat the generated OpenAPI client as SPA JSON
 transport

Record the regen-only generated tree, http adapter value-import rule, and same-origin /api/v1 base URL; e2e now matches Request-based fetch including trailing slashes.
---
 AGENTS.md                  |  60 +++---
 docs/README.md             |  82 ++++----
 frontend/e2e/smoke.spec.ts | 393 +++++++++++++++----------------------
 3 files changed, 231 insertions(+), 304 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 2f4f3341..401b430f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -58,20 +58,20 @@ See [docs/design-system.md](docs/design-system.md) for visual rules.
 
 Public feed-directory metadata for embedded and local configs.
 
-| Item | Detail |
-| --- | --- |
-| Endpoint | `GET /api/v1/configs` |
-| Flag | `CONFIG_CATALOG_ENABLED` (default `true`; set `false` to disable) |
-| Disabled response | `404` with `{ "error": "catalog_disabled" }` |
-| Embedded entries | `Html2rss::Configs::Catalog.entries` — do not re-walk YAML in the handler |
-| Local entries | `Catalog::Merge` includes `feeds.yml` feeds only when `directory.title` is set |
-| Starter feeds (UI) | Server `meta.starters` via `Catalog::Starters.pick`; frontend `selectStarterFeeds(entries, starters)` |
-| Catalog find | `findCatalogEntries` → multi-hit list under create URL; demotes `empty`/`error`; links via `catalogFeedHref` |
-| last_result | Required on every catalog entry (`ok`/`empty`/`error`/`unknown`); process-local `Feeds::LastResults` |
-| catalog_version | `2` (clients fail-closed on other versions) |
-| CORS | Route-scoped on `/api/v1/configs` only (`GET`, `OPTIONS`) |
-| Root metadata | `GET /api/v1/` exposes `instance.catalog: { enabled, url }` |
-| Contract SSOT | Request specs under `spec/html2rss/web/api/v1_spec.rb` and generated `public/openapi.yaml` |
+| Item               | Detail                                                                                                       |
+| ------------------ | ------------------------------------------------------------------------------------------------------------ |
+| Endpoint           | `GET /api/v1/configs`                                                                                        |
+| Flag               | `CONFIG_CATALOG_ENABLED` (default `true`; set `false` to disable)                                            |
+| Disabled response  | `404` with `{ "error": "catalog_disabled" }`                                                                 |
+| Embedded entries   | `Html2rss::Configs::Catalog.entries` — do not re-walk YAML in the handler                                    |
+| Local entries      | `Catalog::Merge` includes `feeds.yml` feeds only when `directory.title` is set                               |
+| Starter feeds (UI) | Server `meta.starters` via `Catalog::Starters.pick`; frontend `selectStarterFeeds(entries, starters)`        |
+| Catalog find       | `findCatalogEntries` → multi-hit list under create URL; demotes `empty`/`error`; links via `catalogFeedHref` |
+| last_result        | Required on every catalog entry (`ok`/`empty`/`error`/`unknown`); process-local `Feeds::LastResults`         |
+| catalog_version    | `2` (clients fail-closed on other versions)                                                                  |
+| CORS               | Route-scoped on `/api/v1/configs` only (`GET`, `OPTIONS`)                                                    |
+| Root metadata      | `GET /api/v1/` exposes `instance.catalog: { enabled, url }`                                                  |
+| Contract SSOT      | Request specs under `spec/html2rss/web/api/v1_spec.rb` and generated `public/openapi.yaml`                   |
 
 After handler or envelope changes: `make openapi` and `make ci-ready`.
 
@@ -79,15 +79,27 @@ After handler or envelope changes: `make openapi` and `make ci-ready`.
 
 Token-holder refinement of the selectors subtree, then generate via create.
 
-| Item | Detail |
-| --- | --- |
-| Endpoints | `POST /api/v1/feeds/validate`, `POST /api/v1/feeds/preview`, `POST /api/v1/feeds/suggest_selectors` |
-| Create | `POST /api/v1/feeds` accepts optional `selectors` (same access token and flag as validate; URL-only create is unaffected by the flag) |
-| Flag | `STUDIO_ENABLED` (development/test default `true`; otherwise `false`) |
-| Disabled response | `403` when the flag is off |
-| Auth | Access token required on validate, preview, suggest, and create |
-| Live fetch | Preview and suggest also need `AUTO_SOURCE_ENABLED` |
-| Frontend | `#/refine` is memory-bound; missing URL recovers to remounted `#/create` |
-| Contract SSOT | Request specs under `spec/html2rss/web/api/v1_spec.rb` and generated `public/openapi.yaml` |
+| Item              | Detail                                                                                                                                |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| Endpoints         | `POST /api/v1/feeds/validate`, `POST /api/v1/feeds/preview`, `POST /api/v1/feeds/suggest_selectors`                                   |
+| Create            | `POST /api/v1/feeds` accepts optional `selectors` (same access token and flag as validate; URL-only create is unaffected by the flag) |
+| Flag              | `STUDIO_ENABLED` (development/test default `true`; otherwise `false`)                                                                 |
+| Disabled response | `403` when the flag is off                                                                                                            |
+| Auth              | Access token required on validate, preview, suggest, and create                                                                       |
+| Live fetch        | Preview and suggest also need `AUTO_SOURCE_ENABLED`                                                                                   |
+| Frontend          | `#/refine` is memory-bound; missing URL recovers to remounted `#/create`                                                              |
+| Contract SSOT     | Request specs under `spec/html2rss/web/api/v1_spec.rb` and generated `public/openapi.yaml`                                            |
 
 After handler or envelope changes: `make openapi` and `make ci-ready`.
+
+## Generated OpenAPI SPA transport
+
+The frontend JSON API is the generated Hey API client, not hand-written `fetch`.
+
+| Item          | Detail                                                                                                                                |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| Regen         | `make openapi-client` (`frontend/openapi-ts.config.ts`). Never hand-edit `frontend/src/api/generated/**`                              |
+| Value imports | Only `frontend/src/api/http/*.ts` and `src/__tests__/apiHttp*.test.ts`. Type-only imports are allowed elsewhere                       |
+| Layers        | Generated owns wire. Adapters in `frontend/src/api/http/` own transport (`unwrap` → `{ ok, status, body }`). Parsers own domain types |
+| baseUrl       | `/api/v1` same-origin. Do not change public OpenAPI `servers` or `RSpec::OpenAPI.servers`                                             |
+| Preview       | JSON Feed stays `fetch(json_public_url)`. Do not use `renderFeedByToken`                                                              |
diff --git a/docs/README.md b/docs/README.md
index f041f4ea..f515a1c1 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -38,28 +38,28 @@ Running the app directly on the host is not supported.
 
 ### Common Commands (Inside Dev Container)
 
-| Command                        | Purpose                                                    |
-| ------------------------------ | ---------------------------------------------------------- |
-| `make setup`                   | Install Ruby and Node dependencies.                        |
-| `make dev`                     | Run Ruby (port 4000) and frontend (port 4001) dev servers. |
-| `make ready`                   | Pre-commit gate: `make quick-check` + `bundle exec rspec`. |
+| Command                        | Purpose                                                                    |
+| ------------------------------ | -------------------------------------------------------------------------- |
+| `make setup`                   | Install Ruby and Node dependencies.                                        |
+| `make dev`                     | Run Ruby (port 4000) and frontend (port 4001) dev servers.                 |
+| `make ready`                   | Pre-commit gate: `make quick-check` + `bundle exec rspec`.                 |
 | `make ci-ready`                | CI parity gate: `make ready` + `make openapi-verify` + frontend e2e smoke. |
-| `make test`                    | Run Ruby and frontend test suites.                         |
-| `make lint`                    | Run all linters.                                           |
-| `make yard-verify-public-docs` | Enforce typed YARD docs for public methods in `app/`.      |
-| `make openapi`                 | Regenerate `public/openapi.yaml` from request specs.       |
-| `make openapi-verify`          | Verify generated OpenAPI and frontend client artifacts are current. |
-| `make openapi-lint`            | Lint OpenAPI with Redocly + Spectral.                      |
+| `make test`                    | Run Ruby and frontend test suites.                                         |
+| `make lint`                    | Run all linters.                                                           |
+| `make yard-verify-public-docs` | Enforce typed YARD docs for public methods in `app/`.                      |
+| `make openapi`                 | Regenerate `public/openapi.yaml` from request specs.                       |
+| `make openapi-verify`          | Verify generated OpenAPI and frontend client artifacts are current.        |
+| `make openapi-lint`            | Lint OpenAPI with Redocly + Spectral.                                      |
 
 ### Frontend pnpm Scripts
 
-| Command                 | Purpose                                      |
-| ----------------------- | -------------------------------------------- |
-| `pnpm run dev`          | Vite dev server with hot reload (port 4001). |
-| `pnpm run build`        | Build static assets into `frontend/dist/`.   |
-| `pnpm run lint`         | Run ESLint across the frontend workspace.    |
-| `pnpm run test:run`     | Unit tests (Vitest).                         |
-| `pnpm run test:contract`| Contract tests with MSW.                     |
+| Command                  | Purpose                                      |
+| ------------------------ | -------------------------------------------- |
+| `pnpm run dev`           | Vite dev server with hot reload (port 4001). |
+| `pnpm run build`         | Build static assets into `frontend/dist/`.   |
+| `pnpm run lint`          | Run ESLint across the frontend workspace.    |
+| `pnpm run test:run`      | Unit tests (Vitest).                         |
+| `pnpm run test:contract` | Contract tests with MSW.                     |
 
 Development routing defaults:
 
@@ -76,7 +76,7 @@ To change or add API endpoints, follow this sequence:
 1. **Ruby Request Spec**: Define the new behavior or endpoint in `spec/html2rss/web/app_integration_spec.rb` or a dedicated request spec.
 2. **OpenAPI Generation**: Run `make openapi` inside the Dev Container to regenerate `public/openapi.yaml` from the spec metadata.
 3. **Verify Contract**: Run `make openapi-verify` and `make openapi-lint` to ensure the generated file matches the specs and is valid.
-4. **Frontend Client**: Keep generated client artifacts in `frontend/src/api/generated` aligned with `public/openapi.yaml`.
+4. **Frontend Client**: Regenerate with `make openapi-client` (`frontend/openapi-ts.config.ts`). Do not hand-edit `frontend/src/api/generated/**`. Only `frontend/src/api/http/*.ts` may value-import that tree; parsers own domain types after unwrap. JSON Feed preview stays `fetch(json_public_url)` and is not the SDK.
 
 Always verify the contract before committing API changes.
 
@@ -140,7 +140,7 @@ make ci-ready
 - Regenerate with `make openapi`.
 - Drift must fail with `make openapi-verify`.
 - Quality must fail with `make openapi-lint`.
-- Frontend generated client code under `frontend/src/api/generated` is machine-generated only.
+- Frontend generated client code under `frontend/src/api/generated` is machine-generated only (`make openapi-client`). Value-import it only from `frontend/src/api/http/*.ts`. The client `baseUrl` is `/api/v1` (same-origin); public OpenAPI `servers` stay unchanged. Domain types live in parsers after unwrap. JSON Feed preview is `fetch(json_public_url)`, not `renderFeedByToken`.
 
 ---
 
@@ -177,6 +177,7 @@ Search these pages for examples, plugins, and configuration options:
 - **Frontend Style**:
   - Follow visual and CSS rules in [design-system.md](design-system.md).
   - Use Preact components in `frontend/src/`.
+  - SPA JSON transport lives in `frontend/src/api/http/` (generated client + unwrap). UI modules must not value-import `frontend/src/api/generated`.
   - Use shared styles in `public/shared-ui.css` or app-specific styles in `frontend/src/styles/`.
   - Do not modify `frontend/dist/` directly.
 - **Testing**:
@@ -189,15 +190,15 @@ Search these pages for examples, plugins, and configuration options:
 
 Managed flags and environment keys:
 
-| Name                              | Env key                           | Type           | Default                                  |
-| --------------------------------- | --------------------------------- | -------------- | ---------------------------------------- |
-| `auto_source_enabled`             | `AUTO_SOURCE_ENABLED`             | boolean        | `true` in development/test, else `false` |
-| `studio_enabled`                  | `STUDIO_ENABLED`                  | boolean        | `true` in development/test, else `false` |
-| `health_check_token`              | `HEALTH_CHECK_TOKEN`              | string         | `nil`                                    |
-| `build_tag`                       | `BUILD_TAG`                       | string         | `unknown` outside production             |
-| `git_sha`                         | `GIT_SHA`                         | string         | `unknown` outside production             |
-| `sentry_dsn`                      | `SENTRY_DSN`                      | string         | `nil`                                    |
-| `sentry_enable_logs`              | `SENTRY_ENABLE_LOGS`              | boolean        | `false`                                  |
+| Name                  | Env key               | Type    | Default                                  |
+| --------------------- | --------------------- | ------- | ---------------------------------------- |
+| `auto_source_enabled` | `AUTO_SOURCE_ENABLED` | boolean | `true` in development/test, else `false` |
+| `studio_enabled`      | `STUDIO_ENABLED`      | boolean | `true` in development/test, else `false` |
+| `health_check_token`  | `HEALTH_CHECK_TOKEN`  | string  | `nil`                                    |
+| `build_tag`           | `BUILD_TAG`           | string  | `unknown` outside production             |
+| `git_sha`             | `GIT_SHA`             | string  | `unknown` outside production             |
+| `sentry_dsn`          | `SENTRY_DSN`          | string  | `nil`                                    |
+| `sentry_enable_logs`  | `SENTRY_ENABLE_LOGS`  | boolean | `false`                                  |
 
 Rules:
 
@@ -221,9 +222,9 @@ Critical-path event families: auth, feed create, feed render, request errors.
 
 Use separate Sentry projects for html2rss-web and botasaurus-scrape-api. Never share a DSN.
 
-| Env var | Service | Project |
-| --- | --- | --- |
-| `SENTRY_DSN` | html2rss-web | A (web) |
+| Env var                 | Service               | Project     |
+| ----------------------- | --------------------- | ----------- |
+| `SENTRY_DSN`            | html2rss-web          | A (web)     |
 | `BOTASAURUS_SENTRY_DSN` | botasaurus-scrape-api | B (scraper) |
 
 Compose maps `BOTASAURUS_SENTRY_DSN` into the botasaurus service as optional (`${BOTASAURUS_SENTRY_DSN:-}`). It does not fall back to web `SENTRY_DSN`. Leave it unset until you want scraper error reporting.
@@ -232,14 +233,14 @@ Compose maps `BOTASAURUS_SENTRY_DSN` into the botasaurus service as optional (`$
 
 Default `docker-compose.yml` aligns botasaurus-scrape-api, the html2rss gem client, and html2rss-web so the scraper exhausts its budget before the web tier aborts the request. Keep **scrape total (45) ≤ feed build (50) ≤ Falcon (55)**; the **work** budget (30) applies only after the browser is ready on the scraper.
 
-| Variable | Service | Default | Role |
-| --- | --- | --- | --- |
-| `SCRAPE_TIMEOUT_SECONDS` | botasaurus-scrape-api | `45` | Handler wall (queue, boot, navigate, wait) |
-| `SCRAPE_WORK_TIMEOUT_SECONDS` | botasaurus-scrape-api | `30` | Post-boot navigate, selector wait, scroll |
-| `BOTASAURUS_SCRAPE_TIMEOUT_SECONDS` | html2rss (web) | `45` | HTTPX POST `/scrape` cap (mirrors scrape total) |
-| `BOTASAURUS_SCRAPE_WORK_TIMEOUT_SECONDS` | html2rss | `30` | Max `wait_timeout_seconds` in feed YAML |
-| `HTML2RSS_TOTAL_TIMEOUT_SECONDS` | html2rss-web | `50` | Feed build budget (scrape + extraction) |
-| `REQUEST_TIMEOUT_SECONDS` | html2rss-web | `55` | Falcon server request timeout |
+| Variable                                 | Service               | Default | Role                                            |
+| ---------------------------------------- | --------------------- | ------- | ----------------------------------------------- |
+| `SCRAPE_TIMEOUT_SECONDS`                 | botasaurus-scrape-api | `45`    | Handler wall (queue, boot, navigate, wait)      |
+| `SCRAPE_WORK_TIMEOUT_SECONDS`            | botasaurus-scrape-api | `30`    | Post-boot navigate, selector wait, scroll       |
+| `BOTASAURUS_SCRAPE_TIMEOUT_SECONDS`      | html2rss (web)        | `45`    | HTTPX POST `/scrape` cap (mirrors scrape total) |
+| `BOTASAURUS_SCRAPE_WORK_TIMEOUT_SECONDS` | html2rss              | `30`    | Max `wait_timeout_seconds` in feed YAML         |
+| `HTML2RSS_TOTAL_TIMEOUT_SECONDS`         | html2rss-web          | `50`    | Feed build budget (scrape + extraction)         |
+| `REQUEST_TIMEOUT_SECONDS`                | html2rss-web          | `55`    | Falcon server request timeout                   |
 
 When triaging `GATEWAY_TIMEOUT`, capacity-shaped `SERVICE_UNAVAILABLE` (queue/boot), or `error_category:timeout`, confirm both projects use this ladder. Scraper terminal timeouts near **45s** with web failures near **50–55s** indicate aligned budgets; scraper failures near **20–25s** while web waits longer usually mean stale `SCRAPE_*` / `BOTASAURUS_*` env on one side. Split queue/boot timeouts from work timeouts before blaming the ladder (see **Alert baselines**).
 
@@ -263,6 +264,7 @@ Start triage from the newest `feed.create`, `feed.render`, and `request.error` e
    - `GATEWAY_TIMEOUT` / `timeout` with `timeout_phase` `work` (or nil transport hop) → slow or hostile target, or timeout ladder mismatch (see **Compose timeout ladder**)
 
 Outer scraper deadlines reclaim Chromium via WorkLease (session force-close) so worker slots free before the HTTP 504 returns; lingering `timeout_phase:queue` under light traffic after deploy usually means reclaim or per-host admit saturation (`SCRAPE_MAX_PER_HOST`), not soft-cancel theater.
+
 ### Alert baselines
 
 After baseline traffic, configure per project:
diff --git a/frontend/e2e/smoke.spec.ts b/frontend/e2e/smoke.spec.ts
index 9f97e499..00622047 100644
--- a/frontend/e2e/smoke.spec.ts
+++ b/frontend/e2e/smoke.spec.ts
@@ -1,36 +1,97 @@
-import { expect, test } from '@playwright/test';
+import { expect, test, type Page } from '@playwright/test';
 import { COPY } from '../src/journey/copy';
 
+const API_ROOT = /\/api\/v1\/?$/;
+const API_CONFIGS = /\/api\/v1\/configs\/?$/;
+const API_FEEDS = /\/api\/v1\/feeds\/?$/;
+const API_VALIDATE = /\/api\/v1\/feeds\/validate\/?$/;
+const API_SUGGEST = /\/api\/v1\/feeds\/suggest_selectors\/?$/;
+const API_STUDIO_PREVIEW = /\/api\/v1\/feeds\/preview\/?$/;
+const API_JSON_PREVIEW = /\/api\/v1\/feeds\/generated-token\.json$/;
+
+function metadataBody(isTokenRequired = true, isCatalogEnabled = true) {
+  return {
+    success: true,
+    data: {
+      api: {
+        name: 'html2rss-web API',
+        description: 'RESTful API for converting websites to RSS feeds',
+        openapi_url: 'https://example.test/openapi.yaml',
+      },
+      instance: {
+        feed_creation: { enabled: true, access_token_required: isTokenRequired },
+        catalog: { enabled: isCatalogEnabled, url: 'https://api.html2rss.dev/api/v1/configs' },
+      },
+    },
+  };
+}
+
+const emptyCatalog = {
+  success: true,
+  data: { configs: [] },
+  meta: { total: 0, catalog_version: 2, starters: [] },
+};
+
+const createdFeed = {
+  success: true,
+  data: {
+    feed: {
+      id: 'feed-123',
+      name: 'Example Feed',
+      url: 'https://example.com/articles',
+      feed_token: 'generated-token',
+      public_url: '/api/v1/feeds/generated-token',
+      json_public_url: '/api/v1/feeds/generated-token.json',
+      created_at: '2026-04-05T08:59:00.000Z',
+      updated_at: '2026-04-05T09:00:00.000Z',
+    },
+  },
+};
+
+async function fulfillJson(
+  page: Page,
+  path: RegExp,
+  body: unknown,
+  status = 200,
+  contentType = 'application/json'
+) {
+  await page.route(path, async (route) => {
+    await route.fulfill({
+      status,
+      contentType,
+      body: JSON.stringify(body),
+    });
+  });
+}
+
+async function stubSpaApi(
+  page: Page,
+  options: { isTokenRequired?: boolean; isCatalogEnabled?: boolean } = {}
+) {
+  const isCatalogEnabled = options.isCatalogEnabled ?? true;
+  await fulfillJson(page, API_ROOT, metadataBody(options.isTokenRequired ?? true, isCatalogEnabled));
+  if (isCatalogEnabled) await fulfillJson(page, API_CONFIGS, emptyCatalog);
+}
+
+function isSameOriginApi(url: string, path: RegExp): boolean {
+  const requested = new URL(url);
+  return path.test(requested.pathname) && requested.host !== 'api.html2rss.dev';
+}
+
 test.describe('frontend smoke', () => {
   test('loads create flow and inline access-token gate', async ({ page }) => {
-    await page.route(/\/api\/v1$/, async (route) => {
-      await route.fulfill({
-        status: 200,
-        contentType: 'application/json',
-        body: JSON.stringify({
-          success: true,
-          data: {
-            api: {
-              name: 'html2rss-web API',
-              description: 'RESTful API for converting websites to RSS feeds',
-              openapi_url: 'https://example.test/openapi.yaml',
-            },
-            instance: {
-              feed_creation: {
-                enabled: true,
-                access_token_required: true,
-              },
-              catalog: { enabled: true, url: '/api/v1/configs' },
-            },
-          },
-        }),
-      });
+    const catalogUrls: string[] = [];
+    page.on('request', (request) => {
+      if (API_CONFIGS.test(new URL(request.url()).pathname)) catalogUrls.push(request.url());
     });
+    await stubSpaApi(page);
 
     await page.goto('/');
 
     await expect(page.getByLabel(COPY.urlLabel)).toBeVisible();
     await expect(page.getByRole('button', { name: COPY.createFeed })).toBeVisible();
+    expect(catalogUrls.length).toBeGreaterThan(0);
+    expect(catalogUrls.every((url) => isSameOriginApi(url, API_CONFIGS))).toBe(true);
 
     await page.getByLabel(COPY.urlLabel).fill('https://example.com/articles');
     await page.getByRole('button', { name: COPY.createFeed }).click();
@@ -52,46 +113,23 @@ test.describe('frontend smoke', () => {
   });
 
   test('remounts create from BrandLockup and hashbang and clears creation chrome', async ({ page }) => {
-    await page.route(/\/api\/v1$/, async (route) => {
-      await route.fulfill({
-        status: 200,
-        contentType: 'application/json',
-        body: JSON.stringify({
-          success: true,
-          data: {
-            api: {
-              name: 'html2rss-web API',
-              description: 'RESTful API for converting websites to RSS feeds',
-              openapi_url: 'https://example.test/openapi.yaml',
-            },
-            instance: {
-              feed_creation: {
-                enabled: true,
-                access_token_required: false,
-              },
-              catalog: { enabled: true, url: '/api/v1/configs' },
-            },
-          },
-        }),
-      });
-    });
-    await page.route(/\/api\/v1\/feeds$/, async (route) => {
-      await route.fulfill({
-        status: 500,
-        contentType: 'application/json',
-        body: JSON.stringify({
-          success: false,
-          error: {
-            kind: 'server',
-            code: 'INTERNAL_SERVER_ERROR',
-            retryable: true,
-            next_action: 'retry',
-            retry_action: 'primary',
-            message: 'Access denied',
-          },
-        }),
-      });
-    });
+    await stubSpaApi(page, { isTokenRequired: false });
+    await fulfillJson(
+      page,
+      API_FEEDS,
+      {
+        success: false,
+        error: {
+          kind: 'server',
+          code: 'INTERNAL_SERVER_ERROR',
+          retryable: true,
+          next_action: 'retry',
+          retry_action: 'primary',
+          message: 'Access denied',
+        },
+      },
+      500
+    );
 
     await page.goto('/#/create');
 
@@ -119,68 +157,24 @@ test.describe('frontend smoke', () => {
   test('shows result after successful feed creation and recovers unmatched result routes onto create', async ({
     page,
   }) => {
-    await page.route(/\/api\/v1$/, async (route) => {
-      await route.fulfill({
-        status: 200,
-        contentType: 'application/json',
-        body: JSON.stringify({
-          success: true,
-          data: {
-            api: {
-              name: 'html2rss-web API',
-              description: 'RESTful API for converting websites to RSS feeds',
-              openapi_url: 'https://example.test/openapi.yaml',
-            },
-            instance: {
-              feed_creation: {
-                enabled: true,
-                access_token_required: true,
-              },
-              catalog: { enabled: true, url: '/api/v1/configs' },
-            },
+    await stubSpaApi(page);
+    await fulfillJson(page, API_FEEDS, createdFeed, 201);
+    await fulfillJson(
+      page,
+      API_JSON_PREVIEW,
+      {
+        items: [
+          {
+            title: 'Sample preview item',
+            content_text: 'Current preview fetch includes rendered content.',
+            date_published: '2026-04-05T09:00:00.000Z',
+            url: 'https://example.com/articles/sample-preview-item',
           },
-        }),
-      });
-    });
-
-    await page.route(/\/api\/v1\/feeds$/, async (route) => {
-      await route.fulfill({
-        status: 201,
-        contentType: 'application/json',
-        body: JSON.stringify({
-          success: true,
-          data: {
-            feed: {
-              id: 'feed-123',
-              name: 'Example Feed',
-              url: 'https://example.com/articles',
-              feed_token: 'generated-token',
-              public_url: '/api/v1/feeds/generated-token',
-              json_public_url: '/api/v1/feeds/generated-token.json',
-              created_at: '2026-04-05T08:59:00.000Z',
-              updated_at: '2026-04-05T09:00:00.000Z',
-            },
-          },
-        }),
-      });
-    });
-
-    await page.route(/\/api\/v1\/feeds\/generated-token\.json$/, async (route) => {
-      await route.fulfill({
-        status: 200,
-        contentType: 'application/feed+json',
-        body: JSON.stringify({
-          items: [
-            {
-              title: 'Sample preview item',
-              content_text: 'Current preview fetch includes rendered content.',
-              date_published: '2026-04-05T09:00:00.000Z',
-              url: 'https://example.com/articles/sample-preview-item',
-            },
-          ],
-        }),
-      });
-    });
+        ],
+      },
+      200,
+      'application/feed+json'
+    );
 
     await page.addInitScript(() => {
       localStorage.setItem('html2rss_access_token', 'token-123');
@@ -188,7 +182,13 @@ test.describe('frontend smoke', () => {
 
     await page.goto('/');
     await page.getByLabel(COPY.urlLabel).fill('https://example.com/articles');
+
+    const created = page.waitForRequest((request) => {
+      if (request.method() !== 'POST' || !isSameOriginApi(request.url(), API_FEEDS)) return false;
+      return request.headers().authorization === 'Bearer token-123';
+    });
     await page.getByRole('button', { name: COPY.createFeed }).click();
+    await created;
 
     await expect(page.getByText(COPY.feedReady)).toBeVisible();
     await expect(page.locator('.result-shell')).toHaveAttribute('data-state', 'result');
@@ -210,26 +210,7 @@ test.describe('frontend smoke', () => {
   });
 
   test('recovers an empty refine route onto remounted create', async ({ page }) => {
-    await page.route(/\/api\/v1$/, async (route) => {
-      await route.fulfill({
-        status: 200,
-        contentType: 'application/json',
-        body: JSON.stringify({
-          success: true,
-          data: {
-            api: {
-              name: 'html2rss-web API',
-              description: 'RESTful API for converting websites to RSS feeds',
-              openapi_url: 'https://example.test/openapi.yaml',
-            },
-            instance: {
-              feed_creation: { enabled: true, access_token_required: true },
-              catalog: { enabled: false, url: '/api/v1/configs' },
-            },
-          },
-        }),
-      });
-    });
+    await stubSpaApi(page, { isCatalogEnabled: false });
 
     await page.goto('/#/refine');
 
@@ -239,103 +220,35 @@ test.describe('frontend smoke', () => {
   });
 
   test('refines a result and generates the feed without a live scrape', async ({ page }) => {
-    await page.route(/\/api\/v1$/, async (route) => {
-      await route.fulfill({
-        status: 200,
-        contentType: 'application/json',
-        body: JSON.stringify({
-          success: true,
-          data: {
-            api: {
-              name: 'html2rss-web API',
-              description: 'RESTful API for converting websites to RSS feeds',
-              openapi_url: 'https://example.test/openapi.yaml',
-            },
-            instance: {
-              feed_creation: { enabled: true, access_token_required: true },
-              catalog: { enabled: false, url: '/api/v1/configs' },
-            },
-          },
-        }),
-      });
-    });
-
-    await page.route(/\/api\/v1\/feeds$/, async (route) => {
-      await route.fulfill({
-        status: 201,
-        contentType: 'application/json',
-        body: JSON.stringify({
-          success: true,
-          data: {
-            feed: {
-              id: 'feed-123',
-              name: 'Example Feed',
-              url: 'https://example.com/articles',
-              feed_token: 'generated-token',
-              public_url: '/api/v1/feeds/generated-token',
-              json_public_url: '/api/v1/feeds/generated-token.json',
-              created_at: '2026-04-05T08:59:00.000Z',
-              updated_at: '2026-04-05T09:00:00.000Z',
-            },
-          },
-        }),
-      });
+    await stubSpaApi(page, { isCatalogEnabled: false });
+    await fulfillJson(page, API_FEEDS, createdFeed, 201);
+    await fulfillJson(page, API_JSON_PREVIEW, { items: [] }, 200, 'application/feed+json');
+    await fulfillJson(page, API_VALIDATE, {
+      success: true,
+      data: {
+        report: { success: true, issues: [] },
+        selectors: { items: { selector: 'article', enhance: false } },
+        yaml: 'selectors:\n  items:\n    selector: article\n    enhance: false\n',
+      },
     });
-
-    await page.route(/\/api\/v1\/feeds\/generated-token\.json$/, async (route) => {
-      await route.fulfill({
-        status: 200,
-        contentType: 'application/feed+json',
-        body: JSON.stringify({ items: [] }),
-      });
+    await fulfillJson(page, API_SUGGEST, {
+      success: true,
+      data: {
+        selectors: { items: { selector: 'article', enhance: false } },
+        segment_strategy: 'list',
+        admission_drops: { chrome: 0 },
+        enhance: false,
+      },
     });
-
-    await page.route(/\/api\/v1\/feeds\/validate$/, async (route) => {
-      await route.fulfill({
-        status: 200,
-        contentType: 'application/json',
-        body: JSON.stringify({
-          success: true,
-          data: {
-            report: { success: true, issues: [] },
-            selectors: { items: { selector: 'article', enhance: false } },
-            yaml: 'selectors:\n  items:\n    selector: article\n    enhance: false\n',
-          },
-        }),
-      });
-    });
-
-    await page.route(/\/api\/v1\/feeds\/suggest_selectors$/, async (route) => {
-      await route.fulfill({
-        status: 200,
-        contentType: 'application/json',
-        body: JSON.stringify({
-          success: true,
-          data: {
-            selectors: { items: { selector: 'article', enhance: false } },
-            segment_strategy: 'list',
-            admission_drops: { chrome: 0 },
-            enhance: false,
-          },
-        }),
-      });
-    });
-
-    await page.route(/\/api\/v1\/feeds\/preview$/, async (route) => {
-      await route.fulfill({
-        status: 200,
-        contentType: 'application/json',
-        body: JSON.stringify({
-          success: true,
-          data: {
-            item_count: 0,
-            sample_items: [],
-            quality_report: { warnings: [], metrics: { short_title_count: 0 } },
-            failure_kind: '',
-            validation_issues: [],
-          },
-        }),
-      });
+    await fulfillJson(page, API_STUDIO_PREVIEW, {
+      success: true,
+      data: {
+        item_count: 0,
+        sample_items: [],
+        quality_report: { warnings: [], metrics: { short_title_count: 0 } },
+        failure_kind: '',
+        validation_issues: [],
+      },
     });
 
     await page.addInitScript(() => {
@@ -357,7 +270,7 @@ test.describe('frontend smoke', () => {
     await expect(save).toBeEnabled();
 
     const refined = page.waitForRequest((request) => {
-      if (request.method() !== 'POST' || !request.url().endsWith('/api/v1/feeds')) return false;
+      if (request.method() !== 'POST' || !isSameOriginApi(request.url(), API_FEEDS)) return false;
       return request.postData()?.includes('"selectors"') ?? false;
     });
     await save.click();

From 80e7d07f7cd58e56c7ef4de5e9f4f0dec97a5fd1 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 20 Sep 2026 11:07:28 +0200
Subject: [PATCH 035/108] feat(studio): make refine a single-rail meadow with
 studio gating

Collapse #/refine onto the Create/Result frame with an editable URL, hide
cleanup and studio-off Refine, and document Sam/Alex/Morgan/Riley surfaces.
---
 AGENTS.md                                     |   6 +-
 app/web/api/v1/root_metadata.rb               |  33 +-
 docs/README.md                                |   3 +-
 docs/design-system.md                         |   2 +-
 docs/personas.md                              |  49 ++
 frontend/e2e/smoke.spec.ts                    |   1 +
 frontend/src/__tests__/App.test.tsx           |   4 +
 frontend/src/__tests__/ConfigStudio.test.tsx  | 103 +++-
 frontend/src/__tests__/ResultDisplay.test.tsx |  64 +++
 .../src/__tests__/apiHttp.metadata.test.ts    |   1 +
 frontend/src/__tests__/mocks/server.ts        |   3 +
 frontend/src/__tests__/useFeedFlow.test.ts    |   1 +
 frontend/src/__tests__/useSession.test.ts     |  17 +
 frontend/src/api/contracts.ts                 |   3 +
 frontend/src/api/generated/types.gen.ts       |   3 +
 frontend/src/components/App.tsx               |  16 +-
 frontend/src/components/AppPanels.tsx         |   5 +-
 frontend/src/components/ConfigStudio.tsx      | 451 ++++++++----------
 frontend/src/components/ResultDisplay.tsx     |  10 +-
 frontend/src/feed/useFeedFlow.ts              |  20 +-
 frontend/src/journey/copy.ts                  |   9 +-
 frontend/src/session/useSession.ts            |   3 +
 frontend/src/studio/useStudio.ts              |   5 +-
 frontend/src/styles/main.css                  |  30 +-
 public/openapi.yaml                           |   8 +
 spec/html2rss/web/api/v1_spec.rb              |   8 +
 26 files changed, 543 insertions(+), 315 deletions(-)
 create mode 100644 docs/personas.md

diff --git a/AGENTS.md b/AGENTS.md
index 401b430f..e4f3b193 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -70,7 +70,7 @@ Public feed-directory metadata for embedded and local configs.
 | last_result        | Required on every catalog entry (`ok`/`empty`/`error`/`unknown`); process-local `Feeds::LastResults`         |
 | catalog_version    | `2` (clients fail-closed on other versions)                                                                  |
 | CORS               | Route-scoped on `/api/v1/configs` only (`GET`, `OPTIONS`)                                                    |
-| Root metadata      | `GET /api/v1/` exposes `instance.catalog: { enabled, url }`                                                  |
+| Root metadata      | `GET /api/v1/` exposes `instance.catalog: { enabled, url }` and `instance.studio: { enabled }`              |
 | Contract SSOT      | Request specs under `spec/html2rss/web/api/v1_spec.rb` and generated `public/openapi.yaml`                   |
 
 After handler or envelope changes: `make openapi` and `make ci-ready`.
@@ -83,11 +83,11 @@ Token-holder refinement of the selectors subtree, then generate via create.
 | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
 | Endpoints         | `POST /api/v1/feeds/validate`, `POST /api/v1/feeds/preview`, `POST /api/v1/feeds/suggest_selectors`                                   |
 | Create            | `POST /api/v1/feeds` accepts optional `selectors` (same access token and flag as validate; URL-only create is unaffected by the flag) |
-| Flag              | `STUDIO_ENABLED` (development/test default `true`; otherwise `false`)                                                                 |
+| Flag              | `STUDIO_ENABLED` (development/test default `true`; otherwise `false`); advertised as `instance.studio.enabled` on `GET /api/v1` |
 | Disabled response | `403` when the flag is off                                                                                                            |
 | Auth              | Access token required on validate, preview, suggest, and create                                                                       |
 | Live fetch        | Preview and suggest also need `AUTO_SOURCE_ENABLED`                                                                                   |
-| Frontend          | `#/refine` is memory-bound; missing URL recovers to remounted `#/create`                                                              |
+| Frontend          | `#/refine` is memory-bound meadow recovery; missing URL or studio-off recovers/bounces to remounted `#/create`                        |
 | Contract SSOT     | Request specs under `spec/html2rss/web/api/v1_spec.rb` and generated `public/openapi.yaml`                                            |
 
 After handler or envelope changes: `make openapi` and `make ci-ready`.
diff --git a/app/web/api/v1/root_metadata.rb b/app/web/api/v1/root_metadata.rb
index 562f5a86..d04f6c1b 100644
--- a/app/web/api/v1/root_metadata.rb
+++ b/app/web/api/v1/root_metadata.rb
@@ -27,14 +27,31 @@ def build(router)
             # @return [Hash{Symbol=>Object}]
             def instance_payload(router)
               {
-                feed_creation: {
-                  enabled: Flags.auto_source_enabled?,
-                  access_token_required: Flags.auto_source_enabled?
-                },
-                catalog: {
-                  enabled: Flags.config_catalog_enabled?,
-                  url: "#{router.base_url}/api/v1/configs"
-                }
+                feed_creation: feed_creation_payload,
+                studio: studio_payload,
+                catalog: catalog_payload(router)
+              }
+            end
+
+            # @return [Hash{Symbol=>Boolean}]
+            def feed_creation_payload
+              {
+                enabled: Flags.auto_source_enabled?,
+                access_token_required: Flags.auto_source_enabled?
+              }
+            end
+
+            # @return [Hash{Symbol=>Boolean}]
+            def studio_payload
+              { enabled: Flags.studio_enabled? }
+            end
+
+            # @param router [Roda::RodaRequest]
+            # @return [Hash{Symbol=>Object}]
+            def catalog_payload(router)
+              {
+                enabled: Flags.config_catalog_enabled?,
+                url: "#{router.base_url}/api/v1/configs"
               }
             end
           end
diff --git a/docs/README.md b/docs/README.md
index f515a1c1..3e007cd5 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -7,6 +7,7 @@ Welcome! This is the canonical source of truth for contributing to `html2rss-web
 - **Start here for contributors**: This document.
 - **Architecture & Request Lifecycle**: [docs/architecture.md](architecture.md)
 - **UI/Design rules**: [docs/design-system.md](design-system.md)
+- **Personas & surface ownership**: [docs/personas.md](personas.md)
 - **Agent execution constraints**: [AGENTS.md](../AGENTS.md)
 - **Generated contract artifacts**: `public/openapi.yaml`
 - **Public-facing intro**: [README.md](../README.md)
@@ -208,7 +209,7 @@ Rules:
 - `BUILD_TAG` and `GIT_SHA` are required in production so startup logs can identify the deployed build.
 - Add or change flags in code, tests, and this table together.
 
-`STUDIO_ENABLED=true` exposes the config refinement studio: `POST /api/v1/feeds/validate`, `POST /api/v1/feeds/preview`, and `POST /api/v1/feeds/suggest_selectors`. All three require a valid access token and return `403 Studio is disabled` when the flag is off. `POST /api/v1/feeds` returns the same `403` when the body carries a `selectors` object, because those selectors are studio output; a body without `selectors` stays the automatic path and keeps working with the flag off. `preview` and `suggest_selectors` additionally need `AUTO_SOURCE_ENABLED=true` because they fetch the caller's URL live, and they only accept URLs the caller's account is allowed to reach. Leave the flag off in production unless you intend to let token holders run live extraction against arbitrary allowed URLs.
+`STUDIO_ENABLED=true` exposes the config refinement studio: `POST /api/v1/feeds/validate`, `POST /api/v1/feeds/preview`, and `POST /api/v1/feeds/suggest_selectors`. All three require a valid access token and return `403 Studio is disabled` when the flag is off. `POST /api/v1/feeds` returns the same `403` when the body carries a `selectors` object, because those selectors are studio output; a body without `selectors` stays the automatic path and keeps working with the flag off. `preview` and `suggest_selectors` additionally need `AUTO_SOURCE_ENABLED=true` because they fetch the caller's URL live, and they only accept URLs the caller's account is allowed to reach. `GET /api/v1` advertises `instance.studio.enabled` so the SPA can hide Refine and bounce `#/refine` when the flag is off. Leave the flag off in production unless you intend to let token holders run live extraction against arbitrary allowed URLs.
 
 ---
 
diff --git a/docs/design-system.md b/docs/design-system.md
index a193e8d5..272d3b3c 100644
--- a/docs/design-system.md
+++ b/docs/design-system.md
@@ -42,7 +42,7 @@ If a page looks like it came from a different product, the change is wrong even
 - **Token gate:** a native `<dialog>` over the still-mounted, inert URL task (one interactive task). Auth copy is in-field (`tokenError`); ActionFeedback stays on create. Access Token persists until Logout with no storage UI.
 - **Result:** primary CTA is **Copy feed URL**. Open feed / JSON / feed-reader are demoted secondary actions and stay available while preview loads. Preview is non-blocking confirmation only. **Refine selectors** is one quiet action beside create another.
 - **Empty extraction:** **Refine selectors** is one quiet action beside Try again when the extraction is empty. It is not offered for other create errors.
-- **Refine:** `#/refine` is memory-bound. No token in the route. A missing in-memory URL recovers onto remounted `#/create`. The items selector is the task; an empty selector is filled once from suggestion, and Enhance follows that suggestion until the user changes either. Controls use one grammar: eyebrow above the control, stacked with token gaps. **Apply suggestion** is its own quiet button, not a label beside the primary. A live preview pane auto-refreshes after validation; an authenticated session may show a sample image when the preview item includes an image URL. Fix a field is limited to Title, Link, and Published date. View as YAML is read-only and demoted under the primary. When the page already publishes a feed, that notice sits above the columns. Primary completion is **Save and generate feed**, which returns to the result view. Focus is the items selector.
+- **Refine:** `#/refine` is memory-bound Sam recovery (see [personas.md](personas.md) J2/J3/J3b). No token in the route. Same frame as Create/Result: one `layout-rail-reading` / `layout-stack` rail — never a two-column paddock. An editable **URL** field (same vocabulary as Create, `input--mono`, no trailing CTA) sits under the title; changing it re-suggests and re-previews without leaving refine or running catalog find. Empty URL recovers onto remounted `#/create`. The items selector is the task; an empty selector is filled once from suggestion, and Enhance follows that suggestion until the user changes either. Controls use one grammar: eyebrow above the control, stacked with token gaps. **Apply suggestion** is `btn--quiet` on the items field. Enhance is one row (eyebrow + checkbox). **Save and generate feed** is the only `btn--primary`, in `ui-actions` like Result. A live preview meadow (`.ui-item-list`) grows below quiet Title/Link/Published meta after validation; an authenticated session may show a sample image when the preview item includes an image URL. Fix a field opens one selector panel **in the stack** for Title, Link, or Published date (no strip/trim/affix cleanup). View as YAML is read-only, demoted, and captioned as a selectors fragment — not a feeds.yml. Native-feed and save-failure Notices sit on the same rail (wire `Decision#message` for save failures — never create-journey copy). When studio is disabled on the instance, Refine actions stay hidden and `#/refine` bounces to create. Focus is the items selector.
 - **Unmatched result:** `#/result/:token` is valid only with a matching in-memory result. Missing or mismatched tokens recover onto remounted `#/create` (no API rehydrate, no failure chrome, no durable shareable result page).
 - **Status eyebrow:** one vocabulary (`Feed ready`) on the result header; preview progress lives in the preview section.
 - **Focus:** create autofocuses the URL field; token autofocuses the token field; result focuses the Copy control; refine focuses the items selector.
diff --git a/docs/personas.md b/docs/personas.md
new file mode 100644
index 00000000..f21cd0c5
--- /dev/null
+++ b/docs/personas.md
@@ -0,0 +1,49 @@
+# Personas and surface ownership
+
+Canonical product personas for html2rss. A persona without a named surface is a feature magnet — do not invent SPA work for journeys that already have an owning surface.
+
+Related: [design-system.md](design-system.md) Journey Grammar (SPA chrome), [README.md](README.md) operator flags, gem MCP docs (`mcp-server`, `ai-agent-workflows`), and the `html2rss-configs` skill (`new` / `repair` / `expand`).
+
+## Surface ownership
+
+| Persona | Job | Owning surface | html2rss-web role | Not this surface |
+| --- | --- | --- | --- | --- |
+| **Sam** (SPA primary) | Follow a site that has no feed | SPA: URL → Result → Copy | Create, token, catalog find, refine recovery | YAML authoring, MCP, directory PRs |
+| **Alex** (operator) | Run a private instance | Compose + env flags | Token, catalog, `feeds.yml` mount, `STUDIO_ENABLED` | In-browser config IDE |
+| **Morgan** (AI/MCP) | Agent scrapes and mass-creates feeds for *their* project | Gem MCP (stdio/http) | Optional: loop `POST /api/v1/feeds` to mint **hosted** feed URLs on Alex’s instance | `#/refine` clicks, batch UI, configs repo metadata |
+| **Riley** (configs maintainer) | Automate directory bureaucracy (recon ledger, catalog fields, quality gate, registry) | html2rss-configs skill + MCP `capture` → `test` → `apply` | Downstream: `GET /api/v1/configs` `last_result` as a repair signal after sync | SPA studio, hosted feed tokens as the source of truth |
+
+Bookmarklet is a **Sam on-ramp**, not a fifth persona.
+
+## Sam — SPA primary
+
+- **Job:** Paste a listing URL, get a feed URL, subscribe in a reader.
+- **Owning surface:** html2rss-web SPA.
+- **Golden path:** Create → token (if needed) → Result → **Copy feed URL**.
+- **Recovery only:** `#/refine` appears under **J2** (empty extraction), **J3** (wrong list or missing Title/Link/Published), and **J3b** (wrong listing URL on refine). It is not an authoring product.
+- **Non-goal:** Learning YAML, MCP, or directory contribution through the SPA.
+
+## Alex — operator
+
+- **Job:** Self-host a private instance with the right flags and mounts.
+- **Owning surface:** Docker Compose / env (`AUTO_SOURCE_ENABLED`, `STUDIO_ENABLED`, `CONFIG_CATALOG_ENABLED`, access token, `feeds.yml`).
+- **html2rss-web role:** Configure capability; when studio is off, Refine stays hidden and `#/refine` bounces to create.
+- **Non-goal:** An in-browser config IDE as a substitute for CLI, MCP, or mounted YAML.
+
+## Morgan — AI / MCP agent
+
+- **Job:** Agent-driven scrape and durable feed configs for *their* projects (including mass create).
+- **Owning surface:** html2rss gem MCP — articles now via `scrape` / `batch_scrape`; durable YAML via `capture` → `test` → `apply`.
+- **html2rss-web role (optional):** Authenticated `POST /api/v1/feeds` (and catalog read) to store **hosted** feed URLs on an instance. Selectors belong in MCP first; studio POST bodies are not a second MCP.
+- **Non-goal:** `#/refine`, an SPA batch console, or treating web studio validate/preview/suggest as agent tooling.
+
+## Riley — configs maintainer
+
+- **Job:** Ship curated YAML to html2rss-configs (recon BUILD/DEFER/DROP, `directory.*`, quality gate, registry bundle).
+- **Owning surface:** html2rss-configs skill modes + MCP `capture` → `test` → `apply`, then `registry-build`.
+- **html2rss-web role:** Consumes published bundles; `last_result` on `GET /api/v1/configs` is a repair signal after sync — not an in-app repair dashboard.
+- **Non-goal:** Authoring directory configs in the SPA. **View as YAML** on refine is a selectors fragment, not a `directory.*`-complete configs PR.
+
+## SPA refine scope (Sam only)
+
+`#/refine` is documented only under Sam **J2 / J3 / J3b**. Morgan and Riley journeys never open this screen.
diff --git a/frontend/e2e/smoke.spec.ts b/frontend/e2e/smoke.spec.ts
index 00622047..2e9f3c98 100644
--- a/frontend/e2e/smoke.spec.ts
+++ b/frontend/e2e/smoke.spec.ts
@@ -20,6 +20,7 @@ function metadataBody(isTokenRequired = true, isCatalogEnabled = true) {
       },
       instance: {
         feed_creation: { enabled: true, access_token_required: isTokenRequired },
+        studio: { enabled: true },
         catalog: { enabled: isCatalogEnabled, url: 'https://api.html2rss.dev/api/v1/configs' },
       },
     },
diff --git a/frontend/src/__tests__/App.test.tsx b/frontend/src/__tests__/App.test.tsx
index 3604dc02..4d95d4cf 100644
--- a/frontend/src/__tests__/App.test.tsx
+++ b/frontend/src/__tests__/App.test.tsx
@@ -106,6 +106,7 @@ describe('App', () => {
             enabled: true,
             access_token_required: true,
           },
+          studio: { enabled: true },
           catalog: { enabled: true, url: '/api/v1/configs' },
         },
       },
@@ -153,6 +154,7 @@ describe('App', () => {
             enabled: true,
             access_token_required: false,
           },
+          studio: { enabled: true },
           catalog: { enabled: true, url: '/api/v1/configs' },
         },
       },
@@ -502,6 +504,7 @@ describe('App', () => {
             enabled: false,
             access_token_required: false,
           },
+          studio: { enabled: true },
           catalog: { enabled: true, url: '/api/v1/configs' },
         },
       },
@@ -1319,6 +1322,7 @@ describe('App', () => {
             enabled: true,
             access_token_required: true,
           },
+          studio: { enabled: true },
           catalog: { enabled: true, url: '/api/v1/configs' },
         },
       },
diff --git a/frontend/src/__tests__/ConfigStudio.test.tsx b/frontend/src/__tests__/ConfigStudio.test.tsx
index 76eaeb6d..5c45a350 100644
--- a/frontend/src/__tests__/ConfigStudio.test.tsx
+++ b/frontend/src/__tests__/ConfigStudio.test.tsx
@@ -1,15 +1,34 @@
 import { describe, it, expect, vi } from 'vitest';
-import { render, screen, fireEvent, waitFor } from '@testing-library/preact';
+import { render, screen, fireEvent, waitFor, act } from '@testing-library/preact';
 import { http, HttpResponse } from 'msw';
 import { server } from './mocks/server';
-import { ConfigStudio } from '../components/ConfigStudio';
+import { ConfigStudio, STUDIO_URL_SETTLE_MS } from '../components/ConfigStudio';
 import { COPY } from '../journey/copy';
 
 const pageUrl = 'https://example.com/articles';
 
-function renderStudio(onGenerate = vi.fn<(selectors: Record<string, unknown>) => Promise<void>>()) {
-  render(<ConfigStudio url={pageUrl} token="tok" onGenerate={onGenerate} />);
-  return onGenerate;
+function renderStudio(
+  onGenerate = vi.fn<(selectors: Record<string, unknown>) => Promise<void>>(),
+  {
+    url = pageUrl,
+    onUrlChange = vi.fn(),
+    onUrlCleared = vi.fn(),
+  }: {
+    url?: string;
+    onUrlChange?: (url: string) => void;
+    onUrlCleared?: () => void;
+  } = {}
+) {
+  render(
+    <ConfigStudio
+      url={url}
+      token="tok"
+      onUrlChange={onUrlChange}
+      onUrlCleared={onUrlCleared}
+      onGenerate={onGenerate}
+    />
+  );
+  return { onGenerate, onUrlChange, onUrlCleared };
 }
 
 function echoValidate() {
@@ -55,15 +74,18 @@ function previewWithImage() {
 }
 
 describe('ConfigStudio', () => {
-  it('focuses the items selector and keeps the attribute builder hidden', async () => {
+  it('focuses the items selector on a single-rail meadow with an editable URL', async () => {
     renderStudio();
 
     const items = screen.getByLabelText(COPY.itemsSelector);
+    const urlField = screen.getByLabelText(COPY.urlLabel);
+    expect(urlField).toHaveValue(pageUrl);
+    expect(document.querySelector('.refine-columns')).toBeNull();
     expect(screen.getByRole('button', { name: COPY.saveAndGenerate })).toBeDisabled();
     expect(screen.queryByRole('combobox')).not.toBeInTheDocument();
     expect(document.querySelector('textarea')).toBeNull();
-    expect(screen.queryByText(COPY.stripHtml)).not.toBeInTheDocument();
-    expect(screen.queryByText(COPY.cleanup)).not.toBeInTheDocument();
+    expect(screen.queryByText(/Cleanup/i)).not.toBeInTheDocument();
+    expect(screen.queryByText(/Strip HTML/i)).not.toBeInTheDocument();
     await waitFor(() => expect(items).toHaveFocus());
     await waitFor(() => expect(items).toHaveValue('article'));
     expect(screen.getByLabelText(COPY.enhanceItems)).toBeInTheDocument();
@@ -73,6 +95,49 @@ describe('ConfigStudio', () => {
     expect(screen.getByRole('button', { name: COPY.fieldMissing(COPY.fieldPublished) })).toBeInTheDocument();
     expect(screen.getByText(COPY.previewFetchedCaption)).toBeInTheDocument();
     await waitFor(() => expect(screen.getByRole('button', { name: COPY.saveAndGenerate })).toBeEnabled());
+    expect(screen.getByRole('button', { name: COPY.saveAndGenerate }).closest('.ui-actions')).not.toBeNull();
+  });
+
+  it('re-suggests when the URL settles on a new listing', async () => {
+    vi.useFakeTimers({ shouldAdvanceTime: true });
+    echoValidate();
+    const suggestBodies: unknown[] = [];
+    server.use(
+      http.post('/api/v1/feeds/suggest_selectors', async ({ request }) => {
+        suggestBodies.push(await request.json());
+        return HttpResponse.json({
+          success: true,
+          data: {
+            selectors: { items: { selector: 'article', enhance: false } },
+            segment_strategy: 'list',
+            admission_drops: {},
+            enhance: false,
+          },
+        });
+      })
+    );
+
+    const { onUrlChange } = renderStudio();
+    await waitFor(() => expect(suggestBodies.length).toBeGreaterThanOrEqual(1));
+
+    fireEvent.input(screen.getByLabelText(COPY.urlLabel), {
+      target: { value: 'https://example.com/blog' },
+    });
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(STUDIO_URL_SETTLE_MS);
+    });
+
+    expect(onUrlChange).toHaveBeenCalledWith('https://example.com/blog');
+    await waitFor(() => expect(suggestBodies.length).toBeGreaterThanOrEqual(2));
+    expect(suggestBodies.at(-1)).toMatchObject({ url: 'https://example.com/blog' });
+    vi.useRealTimers();
+  });
+
+  it('recovers to create when the URL is cleared on blur', () => {
+    const { onUrlCleared } = renderStudio();
+    fireEvent.input(screen.getByLabelText(COPY.urlLabel), { target: { value: ' '.repeat(3) } });
+    fireEvent.blur(screen.getByLabelText(COPY.urlLabel));
+    expect(onUrlCleared).toHaveBeenCalledTimes(1);
   });
 
   it('checks enhance from suggestion and prefills an empty items selector', async () => {
@@ -97,8 +162,8 @@ describe('ConfigStudio', () => {
     expect(screen.getByLabelText(COPY.enhanceItems)).toBeChecked();
     expect(screen.queryByText('list')).not.toBeInTheDocument();
     expect(screen.queryByText(/chrome/)).not.toBeInTheDocument();
-    expect(screen.getByRole('button', { name: COPY.applySuggestion })).toHaveClass('btn--ghost');
-    expect(screen.getByRole('button', { name: COPY.saveAndGenerate }).closest('.ui-actions')).toBeNull();
+    expect(screen.getByRole('button', { name: COPY.applySuggestion })).toHaveClass('btn--quiet');
+    expect(screen.getByRole('button', { name: COPY.saveAndGenerate }).closest('.ui-actions')).not.toBeNull();
   });
 
   it('does not overwrite a typed items selector with the suggestion', async () => {
@@ -148,7 +213,7 @@ describe('ConfigStudio', () => {
     expect(screen.queryByText(/chrome/)).not.toBeInTheDocument();
   });
 
-  it('opens a fix-a-field panel from a hidden validation issue', async () => {
+  it('opens a fix-a-field selector panel without cleanup controls', async () => {
     server.use(
       http.post('/api/v1/feeds/validate', () =>
         HttpResponse.json({
@@ -185,6 +250,7 @@ describe('ConfigStudio', () => {
     expect(screen.getByRole('textbox', { name: /Selector/ })).toHaveFocus();
     expect(screen.getByText('is missing')).toBeInTheDocument();
     expect(screen.queryByText('is invalid')).not.toBeInTheDocument();
+    expect(screen.queryByRole('combobox')).not.toBeInTheDocument();
     expect(screen.getByRole('button', { name: COPY.issueCount(1) })).toBeInTheDocument();
   });
 
@@ -260,7 +326,15 @@ describe('ConfigStudio', () => {
     echoValidate();
     server.use(http.post('/api/v1/feeds/preview', () => HttpResponse.json(previewWithImage())));
 
-    render(<ConfigStudio url={pageUrl} token="  " onGenerate={vi.fn()} />);
+    render(
+      <ConfigStudio
+        url={pageUrl}
+        token="  "
+        onUrlChange={vi.fn()}
+        onUrlCleared={vi.fn()}
+        onGenerate={vi.fn()}
+      />
+    );
 
     await waitFor(() => expect(screen.getByText('With image')).toBeInTheDocument(), { timeout: 4000 });
     expect(document.querySelector('img')).toBeNull();
@@ -278,7 +352,7 @@ describe('ConfigStudio', () => {
     expect(screen.getByText(COPY.previewFetchedCaption)).toBeInTheDocument();
   });
 
-  it('reveals read-only yaml without a textarea', async () => {
+  it('reveals read-only yaml captioned as a selectors fragment', async () => {
     renderStudio();
     await waitFor(() => expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('article'));
 
@@ -286,10 +360,11 @@ describe('ConfigStudio', () => {
 
     expect(document.querySelector('textarea')).toBeNull();
     await waitFor(() => expect(screen.getByText(/selector: article/)).toBeInTheDocument());
+    expect(screen.getByText(COPY.yamlFragmentCaption)).toBeInTheDocument();
   });
 
   it('sends the validated selectors when generating a feed', async () => {
-    const onGenerate = renderStudio();
+    const { onGenerate } = renderStudio();
     const save = screen.getByRole('button', { name: COPY.saveAndGenerate });
     expect(save).toBeDisabled();
     await waitFor(() => expect(save).toBeEnabled());
diff --git a/frontend/src/__tests__/ResultDisplay.test.tsx b/frontend/src/__tests__/ResultDisplay.test.tsx
index 29b27cc4..e1ea5aec 100644
--- a/frontend/src/__tests__/ResultDisplay.test.tsx
+++ b/frontend/src/__tests__/ResultDisplay.test.tsx
@@ -79,6 +79,7 @@ describe('ResultDisplay', () => {
     render(
       <ResultDisplay
         viewModel={viewModelWithMultiplePreviewItems}
+        studioEnabled
         onCreateAnother={mockOnCreateAnother}
         onRefine={mockOnRefine}
         onRetryPreview={mockOnRetryPreview}
@@ -109,6 +110,7 @@ describe('ResultDisplay', () => {
           ...mockViewModel,
           preview: { status: 'preview_loading', items: [], isLoading: true },
         }}
+        studioEnabled
         onCreateAnother={mockOnCreateAnother}
         onRefine={mockOnRefine}
         onRetryPreview={mockOnRetryPreview}
@@ -136,6 +138,7 @@ describe('ResultDisplay', () => {
             },
           ],
         }}
+        studioEnabled
         onCreateAnother={mockOnCreateAnother}
         onRefine={mockOnRefine}
         onRetryPreview={mockOnRetryPreview}
@@ -151,6 +154,7 @@ describe('ResultDisplay', () => {
     render(
       <ResultDisplay
         viewModel={mockViewModel}
+        studioEnabled
         onCreateAnother={mockOnCreateAnother}
         onRefine={mockOnRefine}
         onRetryPreview={mockOnRetryPreview}
@@ -170,6 +174,7 @@ describe('ResultDisplay', () => {
     render(
       <ResultDisplay
         viewModel={mockViewModel}
+        studioEnabled
         onCreateAnother={mockOnCreateAnother}
         onRefine={mockOnRefine}
         onRetryPreview={mockOnRetryPreview}
@@ -198,6 +203,7 @@ describe('ResultDisplay', () => {
             },
           ],
         }}
+        studioEnabled
         onCreateAnother={mockOnCreateAnother}
         onRefine={mockOnRefine}
         onRetryPreview={mockOnRetryPreview}
@@ -225,6 +231,7 @@ describe('ResultDisplay', () => {
             },
           ],
         }}
+        studioEnabled
         onCreateAnother={mockOnCreateAnother}
         onRefine={mockOnRefine}
         onRetryPreview={mockOnRetryPreview}
@@ -239,6 +246,7 @@ describe('ResultDisplay', () => {
     render(
       <ResultDisplay
         viewModel={mockViewModel}
+        studioEnabled
         onCreateAnother={mockOnCreateAnother}
         onRefine={mockOnRefine}
         onRetryPreview={mockOnRetryPreview}
@@ -259,6 +267,21 @@ describe('ResultDisplay', () => {
     fireEvent.click(refine);
     expect(mockOnRefine).toHaveBeenCalledTimes(1);
   });
+
+  it('hides refine when studio is disabled on the instance', () => {
+    render(
+      <ResultDisplay
+        viewModel={mockViewModel}
+        studioEnabled={false}
+        onCreateAnother={mockOnCreateAnother}
+        onRefine={mockOnRefine}
+        onRetryPreview={mockOnRetryPreview}
+      />
+    );
+
+    expect(screen.queryByRole('button', { name: COPY.refineSelectors })).not.toBeInTheDocument();
+    expect(screen.getByRole('button', { name: COPY.createAnother })).toBeInTheDocument();
+  });
 });
 
 function renderEmptyExtractionError(error: FeedCreationError, onRefine = vi.fn(), onRetryCreate = vi.fn()) {
@@ -277,6 +300,7 @@ function renderEmptyExtractionError(error: FeedCreationError, onRefine = vi.fn()
       feedFieldErrors={{ url: '', form: '' }}
       submitDisabled={false}
       feedCreationEnabled
+      studioEnabled
       catalogEntries={[]}
       featuredFeeds={[]}
       tokenDraft=""
@@ -342,4 +366,44 @@ describe('empty extraction refine on-ramp', () => {
     expect(screen.queryByRole('button', { name: COPY.refineSelectors })).not.toBeInTheDocument();
     expect(screen.queryByRole('button', { name: COPY.tryAgain })).not.toBeInTheDocument();
   });
+
+  it('does not offer refine when studio is disabled', () => {
+    const noop = vi.fn();
+    render(
+      <CreateFeedPanel
+        focusComposerKey={0}
+        viewModel={{
+          kind: 'error',
+          message: 'We could not extract feed items from this page yet.',
+          error: {
+            kind: 'input',
+            code: 'EXTRACTION_EMPTY',
+            retryable: true,
+            nextAction: 'retry',
+            retryAction: 'primary',
+            message: 'We could not extract feed items from this page yet.',
+          },
+          errorKind: 'input',
+        }}
+        isCreating={false}
+        feedFormData={{ url: 'https://example.com/articles' }}
+        feedFieldErrors={{ url: '', form: '' }}
+        submitDisabled={false}
+        feedCreationEnabled
+        studioEnabled={false}
+        catalogEntries={[]}
+        featuredFeeds={[]}
+        tokenDraft=""
+        onFeedSubmit={noop}
+        onFeedFieldChange={noop}
+        onTokenDraftChange={noop}
+        onSaveToken={noop}
+        onCancelTokenPrompt={noop}
+        onRetryCreate={noop}
+        onRefine={noop}
+      />
+    );
+
+    expect(screen.queryByRole('button', { name: COPY.refineSelectors })).not.toBeInTheDocument();
+  });
 });
diff --git a/frontend/src/__tests__/apiHttp.metadata.test.ts b/frontend/src/__tests__/apiHttp.metadata.test.ts
index e85ea8d8..f227164a 100644
--- a/frontend/src/__tests__/apiHttp.metadata.test.ts
+++ b/frontend/src/__tests__/apiHttp.metadata.test.ts
@@ -8,6 +8,7 @@ const metadataBody = {
     api: { name: 'html2rss-web API', description: 'd', openapi_url: '/openapi.yaml' },
     instance: {
       feed_creation: { enabled: true, access_token_required: true },
+      studio: { enabled: true },
       catalog: { enabled: true, url: '/api/v1/configs' },
     },
   },
diff --git a/frontend/src/__tests__/mocks/server.ts b/frontend/src/__tests__/mocks/server.ts
index 9d2a8767..9ab39273 100644
--- a/frontend/src/__tests__/mocks/server.ts
+++ b/frontend/src/__tests__/mocks/server.ts
@@ -16,6 +16,9 @@ export const server = setupServer(
             enabled: true,
             access_token_required: true,
           },
+          studio: {
+            enabled: true,
+          },
           catalog: {
             enabled: true,
             url: '/api/v1/configs',
diff --git a/frontend/src/__tests__/useFeedFlow.test.ts b/frontend/src/__tests__/useFeedFlow.test.ts
index b9e35a78..733444b6 100644
--- a/frontend/src/__tests__/useFeedFlow.test.ts
+++ b/frontend/src/__tests__/useFeedFlow.test.ts
@@ -42,6 +42,7 @@ describe('useFeedFlow', () => {
     token: undefined,
     isLoading: false,
     feedCreationEnabled: true,
+    studioEnabled: true,
     mayCreate: () => 'proceed',
     saveToken: mockSaveToken,
     clearToken: mockClearToken,
diff --git a/frontend/src/__tests__/useSession.test.ts b/frontend/src/__tests__/useSession.test.ts
index 17e33793..337c88c9 100644
--- a/frontend/src/__tests__/useSession.test.ts
+++ b/frontend/src/__tests__/useSession.test.ts
@@ -9,6 +9,7 @@ const ACCESS_TOKEN_KEY = 'html2rss_access_token';
 const mockMetadata = {
   instance: {
     feed_creation: { enabled: true, access_token_required: true },
+    studio: { enabled: true },
     catalog: { enabled: true, url: '/api/v1/configs' },
   },
   api: { openapi_url: '/openapi.yaml' },
@@ -178,6 +179,7 @@ describe('useSession', () => {
     expect(result.current.mayCreate()).toBe('needToken');
     expect(result.current.mayCreate('')).toBe('needToken');
     expect(result.current.mayCreate('provided-token')).toBe('proceed');
+    expect(result.current.studioEnabled).toBe(true);
   });
 
   it('mayCreate returns disabled when feed creation is disabled', async () => {
@@ -223,4 +225,19 @@ describe('useSession', () => {
     expect(result.current.feedCreationEnabled).toBe(true);
     expect(result.current.mayCreate()).toBe('needToken');
   });
+
+  it('defaults studio to disabled when metadata studio is absent', async () => {
+    mockFetchFor({
+      ...mockMetadata,
+      instance: {
+        feed_creation: { enabled: true, access_token_required: true },
+        catalog: { enabled: true, url: '/api/v1/configs' },
+      },
+    });
+
+    const { result } = renderHook(() => useSession());
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(result.current.studioEnabled).toBe(false);
+  });
 });
diff --git a/frontend/src/api/contracts.ts b/frontend/src/api/contracts.ts
index 76fffed9..c01a0555 100644
--- a/frontend/src/api/contracts.ts
+++ b/frontend/src/api/contracts.ts
@@ -75,6 +75,9 @@ export interface ApiMetadataRecord {
       enabled: boolean;
       access_token_required: boolean;
     };
+    studio?: {
+      enabled: boolean;
+    };
     catalog?: {
       enabled: boolean;
       url: string;
diff --git a/frontend/src/api/generated/types.gen.ts b/frontend/src/api/generated/types.gen.ts
index 56ee21fc..8a6e7c28 100644
--- a/frontend/src/api/generated/types.gen.ts
+++ b/frontend/src/api/generated/types.gen.ts
@@ -36,6 +36,9 @@ export type GetApiMetadataResponses = {
           access_token_required: boolean;
           enabled: boolean;
         };
+        studio: {
+          enabled: boolean;
+        };
       };
     };
     success: boolean;
diff --git a/frontend/src/components/App.tsx b/frontend/src/components/App.tsx
index 88186158..b534d849 100644
--- a/frontend/src/components/App.tsx
+++ b/frontend/src/components/App.tsx
@@ -44,6 +44,7 @@ export function App() {
     saveToken,
     clearToken,
     feedCreationEnabled,
+    studioEnabled,
     mayCreate,
   } = useSession();
 
@@ -65,6 +66,8 @@ export function App() {
     onCreateAnother,
     generateFromStudio,
     onRefine,
+    onStudioUrlChange,
+    onStudioUrlCleared,
     onRetryPreview,
     sourceUrl,
     setBookmarkletNotice,
@@ -74,6 +77,7 @@ export function App() {
     token,
     isLoading: sessionLoading,
     feedCreationEnabled,
+    studioEnabled,
     mayCreate,
     saveToken,
     clearToken,
@@ -108,13 +112,22 @@ export function App() {
     bodyContent = (
       <ResultDisplay
         viewModel={viewModel}
+        studioEnabled={studioEnabled}
         onCreateAnother={onCreateAnother}
         onRefine={onRefine}
         onRetryPreview={onRetryPreview}
       />
     );
   } else if (viewModel.kind === 'refine') {
-    bodyContent = <ConfigStudio url={sourceUrl} token={token ?? ''} onGenerate={generateFromStudio} />;
+    bodyContent = (
+      <ConfigStudio
+        url={sourceUrl}
+        token={token ?? ''}
+        onUrlChange={onStudioUrlChange}
+        onUrlCleared={onStudioUrlCleared}
+        onGenerate={generateFromStudio}
+      />
+    );
   } else {
     bodyContent = (
       <CreateFeedPanel
@@ -125,6 +138,7 @@ export function App() {
         feedFieldErrors={feedFieldErrors}
         submitDisabled={submitDisabled}
         feedCreationEnabled={feedCreationEnabled}
+        studioEnabled={studioEnabled}
         catalogEntries={catalogEntries}
         featuredFeeds={featuredFeeds}
         tokenDraft={tokenDraft}
diff --git a/frontend/src/components/AppPanels.tsx b/frontend/src/components/AppPanels.tsx
index 94164e73..29d1d076 100644
--- a/frontend/src/components/AppPanels.tsx
+++ b/frontend/src/components/AppPanels.tsx
@@ -27,6 +27,7 @@ interface CreateFeedPanelProperties {
   feedFieldErrors: FeedFieldErrors;
   submitDisabled: boolean;
   feedCreationEnabled: boolean;
+  studioEnabled: boolean;
   catalogEntries: CatalogEntry[];
   featuredFeeds: CatalogEntry[];
   tokenDraft: string;
@@ -410,6 +411,7 @@ export function CreateFeedPanel({
   feedFieldErrors,
   submitDisabled,
   feedCreationEnabled,
+  studioEnabled,
   catalogEntries,
   featuredFeeds,
   tokenDraft,
@@ -439,7 +441,8 @@ export function CreateFeedPanel({
   const isShowRetryButton = Boolean(
     creationError && creationError.nextAction === 'retry' && creationError.retryAction !== 'none'
   );
-  const shouldOfferRefine = viewModel.kind === 'error' && creationError?.code === 'EXTRACTION_EMPTY';
+  const shouldOfferRefine =
+    studioEnabled && viewModel.kind === 'error' && creationError?.code === 'EXTRACTION_EMPTY';
   const isCreatingFeed = !isTokenPrompt && isSubmitting;
   const tokenCreating = isTokenPrompt && flowCreating;
 
diff --git a/frontend/src/components/ConfigStudio.tsx b/frontend/src/components/ConfigStudio.tsx
index 8b452539..bbca2e74 100644
--- a/frontend/src/components/ConfigStudio.tsx
+++ b/frontend/src/components/ConfigStudio.tsx
@@ -3,33 +3,30 @@ import { useEffect, useRef, useState } from 'preact/hooks';
 import { COPY } from '../journey/copy';
 import { PreviewItem } from './PreviewItem';
 import { Notice } from './Notice';
-import {
-  issuePlace,
-  STUDIO_FIELDS,
-  hasIncompleteTrim,
-  type FieldFixup,
-  type StudioFieldId,
-} from '../studio/selectorDraft';
+import { issuePlace, STUDIO_FIELDS, type StudioFieldId } from '../studio/selectorDraft';
 import { canSaveStudio, studioIssues, useStudio, type StudioState } from '../studio/useStudio';
 import type { StudioIssue, StudioSampleItem } from '../studio/studioService';
 
-const FIXUP_KINDS = ['none', 'strip_html', 'trim_length', 'remove_affix'] as const;
-type FixupKind = (typeof FIXUP_KINDS)[number];
+/** Settle delay before URL edits re-trigger suggest / validate / preview. */
+export const STUDIO_URL_SETTLE_MS = 400;
 
 interface ConfigStudioProperties {
   readonly url: string;
   readonly token: string;
+  readonly onUrlChange: (url: string) => void;
+  readonly onUrlCleared: () => void;
   readonly onGenerate: (selectors: Record<string, unknown>) => Promise<void>;
 }
 
 interface OpenPanel {
   readonly field: StudioFieldId;
-  readonly focusId: string;
   readonly nonce: number;
 }
 
-export function ConfigStudio({ url, token, onGenerate }: ConfigStudioProperties) {
-  const studio = useStudio({ url, token });
+export function ConfigStudio({ url, token, onUrlChange, onUrlCleared, onGenerate }: ConfigStudioProperties) {
+  const [urlDraft, setUrlDraft] = useState(url);
+  const [settledUrl, setSettledUrl] = useState(url);
+  const studio = useStudio({ url: settledUrl, token });
   const { state } = studio;
   const issues = studioIssues(state);
   const [panel, setPanel] = useState<OpenPanel | undefined>(undefined);
@@ -45,13 +42,31 @@ export function ConfigStudio({ url, token, onGenerate }: ConfigStudioProperties)
   const nativeFeedUrl = ready?.nativeFeedUrl;
   const isBusy = state.phase === 'validating' || state.phase === 'saving' || state.live.status === 'loading';
 
+  useEffect(() => {
+    setUrlDraft(url);
+    setSettledUrl(url);
+  }, [url]);
+
+  useEffect(() => {
+    const trimmed = urlDraft.trim();
+    if (trimmed === settledUrl.trim()) return;
+
+    const timer = setTimeout(() => {
+      if (!trimmed) return;
+      setSettledUrl(trimmed);
+      onUrlChange(trimmed);
+    }, STUDIO_URL_SETTLE_MS);
+
+    return () => clearTimeout(timer);
+  }, [urlDraft, settledUrl, onUrlChange]);
+
   useEffect(() => {
     itemsReference.current?.focus();
   }, []);
 
   useEffect(() => {
     if (!panel) return;
-    focusElement(panel.focusId);
+    focusElement('studio-field-selector');
   }, [panel]);
 
   useEffect(() => {
@@ -60,149 +75,176 @@ export function ConfigStudio({ url, token, onGenerate }: ConfigStudioProperties)
     };
   }, []);
 
-  const openFieldPanel = (field: StudioFieldId, control: 'selector' | 'fixup') => {
-    const focusId =
-      control === 'selector' ? 'studio-field-selector' : fixupControlId(state.draft.fields[field].fixup);
-    setPanel({ field, focusId, nonce: Date.now() });
+  const openFieldPanel = (field: StudioFieldId) => {
+    setPanel((current) => (current?.field === field ? undefined : { field, nonce: Date.now() }));
   };
 
   const onHiddenIssues = () => {
     const target = firstFieldIssue(hiddenIssues);
-    if (target) openFieldPanel(target.field, target.control);
+    if (target) openFieldPanel(target.field);
     if (unmappedIssues.length > 0) setShowUnmapped(true);
   };
 
+  const onUrlBlur = () => {
+    if (urlDraft.trim()) return;
+    onUrlCleared();
+  };
+
+  const flushUrlBeforeSave = () => {
+    const trimmed = urlDraft.trim();
+    if (!trimmed) {
+      onUrlCleared();
+      return false;
+    }
+    if (trimmed !== settledUrl.trim()) {
+      setSettledUrl(trimmed);
+      onUrlChange(trimmed);
+    }
+    return true;
+  };
+
   return (
     <section
-      class="ui-card ui-card--padded ui-card--framed"
+      class="ui-card ui-card--padded ui-card--framed layout-rail-reading layout-stack"
       data-state="refine"
       aria-labelledby="refine-title"
       aria-busy={isBusy}
     >
-      <div class="layout-stack">
-        <h1 id="refine-title" class="ui-display-title">
-          {COPY.refineSelectors}
-        </h1>
-
-        {nativeFeedUrl ? (
-          <Notice title={COPY.nativeFeedTitle}>
-            <a class="input--mono" href={nativeFeedUrl} target="_blank" rel="noopener noreferrer">
-              {nativeFeedUrl}
-            </a>
-          </Notice>
-        ) : undefined}
+      <h1 id="refine-title" class="ui-display-title">
+        {COPY.refineSelectors}
+      </h1>
 
-        {state.phase === 'failed' ? <Notice title={state.message} tone="error" /> : undefined}
-
-        <div class="refine-columns">
-          <div class="refine-pane layout-stack">
-            <label class="field-block" htmlFor="studio-items-selector">
-              <span class="ui-eyebrow">{COPY.itemsSelector}</span>
-              <input
-                id="studio-items-selector"
-                class="input input--mono"
-                value={state.draft.itemsSelector}
-                autoFocus
-                ref={itemsReference}
-                spellcheck={false}
-                onInput={(event) => studio.setItemsSelector(inputValue(event))}
-              />
-              <FieldErrors
-                messages={messagesFor(issues, (issue) => issuePlace(issue.path).kind === 'items')}
-              />
-            </label>
-
-            <label class="field-block" htmlFor="studio-enhance">
-              <span class="ui-eyebrow">{COPY.enhanceItems}</span>
-              <input
-                id="studio-enhance"
-                class="refine-check"
-                type="checkbox"
-                checked={state.draft.enhance}
-                onChange={(event) => studio.setEnhance(isInputChecked(event))}
-              />
-              <FieldErrors
-                messages={messagesFor(issues, (issue) => issuePlace(issue.path).kind === 'enhance')}
-              />
-            </label>
-
-            {hiddenIssues.length > 0 ? (
-              <button type="button" class="btn btn--quiet btn--linkish" onClick={onHiddenIssues}>
-                {COPY.issueCount(hiddenIssues.length)}
-              </button>
-            ) : undefined}
-
-            {panel ? (
-              <FieldFixPanel
-                field={panel.field}
-                selector={state.draft.fields[panel.field].selector}
-                fixup={state.draft.fields[panel.field].fixup}
-                selectorMessages={fieldMessages(issues, panel.field, 'selector')}
-                fixupMessages={fieldMessages(issues, panel.field, 'fixup')}
-                onSelector={(selector) => studio.setFieldSelector(panel.field, selector)}
-                onFixup={(fixup) => studio.setFieldFixup(panel.field, fixup)}
-              />
-            ) : undefined}
-
-            {showUnmapped && unmappedIssues.length > 0 ? (
-              <Notice tone="error">
-                {unmappedIssues.map((issue) => (
-                  <p key={issueKey(issue)}>{issue.message}</p>
-                ))}
-              </Notice>
-            ) : undefined}
+      <label class="field-block" htmlFor="studio-url">
+        <span class="ui-eyebrow">{COPY.urlLabel}</span>
+        <input
+          id="studio-url"
+          class="input input--mono"
+          type="url"
+          value={urlDraft}
+          spellcheck={false}
+          autoComplete="url"
+          onInput={(event) => setUrlDraft(inputValue(event))}
+          onBlur={onUrlBlur}
+        />
+      </label>
 
+      {nativeFeedUrl ? (
+        <Notice title={COPY.nativeFeedTitle}>
+          <a class="input--mono" href={nativeFeedUrl} target="_blank" rel="noopener noreferrer">
+            {nativeFeedUrl}
+          </a>
+        </Notice>
+      ) : undefined}
+
+      {state.phase === 'failed' ? (
+        <Notice title={COPY.createFailedTitle} tone="error">
+          {state.message.trim() && state.message !== COPY.createFailedTitle ? (
+            <p>{state.message}</p>
+          ) : undefined}
+        </Notice>
+      ) : undefined}
+
+      <label class="field-block" htmlFor="studio-items-selector">
+        <span class="ui-eyebrow">{COPY.itemsSelector}</span>
+        <input
+          id="studio-items-selector"
+          class="input input--mono input--lg"
+          value={state.draft.itemsSelector}
+          autoFocus
+          ref={itemsReference}
+          spellcheck={false}
+          onInput={(event) => studio.setItemsSelector(inputValue(event))}
+        />
+        <FieldErrors messages={messagesFor(issues, (issue) => issuePlace(issue.path).kind === 'items')} />
+      </label>
+
+      <button type="button" class="btn btn--quiet" onClick={() => studio.requestSuggestion()}>
+        {COPY.applySuggestion}
+      </button>
+
+      <div class="refine-enhance">
+        <label class="refine-enhance__label" htmlFor="studio-enhance">
+          <span class="ui-eyebrow">{COPY.enhanceItems}</span>
+          <input
+            id="studio-enhance"
+            class="refine-check"
+            type="checkbox"
+            checked={state.draft.enhance}
+            onChange={(event) => studio.setEnhance(isInputChecked(event))}
+          />
+        </label>
+        <FieldErrors messages={messagesFor(issues, (issue) => issuePlace(issue.path).kind === 'enhance')} />
+      </div>
+
+      {hiddenIssues.length > 0 ? (
+        <button type="button" class="btn btn--quiet btn--linkish" onClick={onHiddenIssues}>
+          {COPY.issueCount(hiddenIssues.length)}
+        </button>
+      ) : undefined}
+
+      {panel ? (
+        <FieldFixPanel
+          field={panel.field}
+          selector={state.draft.fields[panel.field].selector}
+          selectorMessages={fieldMessages(issues, panel.field)}
+          onSelector={(selector) => studio.setFieldSelector(panel.field, selector)}
+        />
+      ) : undefined}
+
+      {showUnmapped && unmappedIssues.length > 0 ? (
+        <Notice tone="error">
+          {unmappedIssues.map((issue) => (
+            <p key={issueKey(issue)}>{issue.message}</p>
+          ))}
+        </Notice>
+      ) : undefined}
+
+      <div class="ui-actions">
+        <button
+          type="button"
+          class="btn btn--primary"
+          disabled={!canSaveStudio(state)}
+          onClick={() => {
+            if (!flushUrlBeforeSave()) return;
+            void studio.save(onGenerate);
+          }}
+        >
+          {state.phase === 'saving' ? COPY.creating : COPY.saveAndGenerate}
+        </button>
+      </div>
+
+      <div class="layout-stack layout-stack--tight">
+        <button
+          type="button"
+          class="btn btn--quiet btn--linkish"
+          onClick={() => setYamlOpen((open) => !open)}
+        >
+          {COPY.viewAsYaml}
+        </button>
+        {yamlOpen ? (
+          <>
+            <pre class="refine-yaml input input--mono">{state.yaml}</pre>
             <button
               type="button"
-              class="btn btn--ghost refine-action"
-              onClick={() => studio.requestSuggestion()}
-            >
-              {COPY.applySuggestion}
-            </button>
-            <button
-              type="button"
-              class="btn btn--primary refine-action"
-              disabled={!canSaveStudio(state)}
+              class="btn btn--quiet btn--linkish"
               onClick={() => {
-                void studio.save(onGenerate);
+                void copyYaml(state.yaml, setCopied, copyResetReference);
               }}
             >
-              {state.phase === 'saving' ? COPY.creating : COPY.saveAndGenerate}
+              {copied ? COPY.copied : COPY.copy}
             </button>
-
-            <div class="layout-stack layout-stack--tight">
-              <button
-                type="button"
-                class="btn btn--quiet btn--linkish"
-                onClick={() => setYamlOpen((open) => !open)}
-              >
-                {COPY.viewAsYaml}
-              </button>
-              {yamlOpen ? (
-                <>
-                  <pre class="refine-yaml input input--mono">{state.yaml}</pre>
-                  <button
-                    type="button"
-                    class="btn btn--quiet btn--linkish"
-                    onClick={() => {
-                      void copyYaml(state.yaml, setCopied, copyResetReference);
-                    }}
-                  >
-                    {copied ? COPY.copied : COPY.copy}
-                  </button>
-                </>
-              ) : undefined}
-            </div>
-          </div>
-
-          <PreviewPane
-            state={state}
-            token={token}
-            onOpenField={openFieldPanel}
-            onRetry={studio.retryPreview}
-          />
-        </div>
+            <p class="field-help">{COPY.yamlFragmentCaption}</p>
+          </>
+        ) : undefined}
       </div>
+
+      <PreviewPane
+        state={state}
+        token={token}
+        openField={openField}
+        onOpenField={openFieldPanel}
+        onRetry={studio.retryPreview}
+      />
     </section>
   );
 }
@@ -210,30 +252,34 @@ export function ConfigStudio({ url, token, onGenerate }: ConfigStudioProperties)
 function PreviewPane({
   state,
   token,
+  openField,
   onOpenField,
   onRetry,
 }: {
   readonly state: StudioState;
   readonly token: string;
-  readonly onOpenField: (field: StudioFieldId, control: 'selector' | 'fixup') => void;
+  readonly openField: StudioFieldId | undefined;
+  readonly onOpenField: (field: StudioFieldId) => void;
   readonly onRetry: () => void;
 }) {
   const items = state.live.status === 'ready' ? state.live.sample.items : [];
   const canShowImages = token.trim().length > 0;
 
   return (
-    <div class="refine-pane layout-stack" aria-label={COPY.previewRegion}>
+    <div class="layout-stack" aria-label={COPY.previewRegion}>
       <p class="field-help">{COPY.previewFetchedCaption}</p>
       <div class="refine-status" role="group" aria-label={COPY.previewStatus}>
         {STUDIO_FIELDS.map((field) => {
           const label = fieldLabel(field);
           const isFound = hasSampleField(items, field);
+          const isOpen = openField === field;
           return (
             <button
               key={field}
               type="button"
-              class="btn btn--quiet btn--linkish"
-              onClick={() => onOpenField(field, 'selector')}
+              class={`btn btn--quiet btn--linkish${isOpen ? ' is-active' : ''}`}
+              aria-pressed={isOpen}
+              onClick={() => onOpenField(field)}
             >
               {isFound ? COPY.fieldFound(label) : COPY.fieldMissing(label)}
             </button>
@@ -258,15 +304,18 @@ function PreviewPane({
       ) : undefined}
 
       {items.length > 0 ? (
-        <ul class="ui-item-list" role="list">
-          {items.map((item, index) => (
-            <li key={sampleKey(item, index)} class="ui-item">
-              {canShowImages && item.imageUrl ? <SampleImage url={item.imageUrl} /> : undefined}
-              <PreviewItem title={item.title} url={item.url} publishedLabel={item.publishedAt} />
-              {item.url ? <p class="ui-item__meta input--mono">{item.url}</p> : undefined}
-            </li>
-          ))}
-        </ul>
+        <>
+          <p class="ui-eyebrow">{COPY.previewItemCount(items.length)}</p>
+          <ul class="ui-item-list" role="list">
+            {items.map((item, index) => (
+              <li key={sampleKey(item, index)} class="ui-item">
+                {canShowImages && item.imageUrl ? <SampleImage url={item.imageUrl} /> : undefined}
+                <PreviewItem title={item.title} url={item.url} publishedLabel={item.publishedAt} />
+                {item.url ? <p class="ui-item__meta input--mono">{item.url}</p> : undefined}
+              </li>
+            ))}
+          </ul>
+        </>
       ) : undefined}
     </div>
   );
@@ -292,22 +341,14 @@ function SampleImage({ url }: { readonly url: string }) {
 function FieldFixPanel({
   field,
   selector,
-  fixup,
   selectorMessages,
-  fixupMessages,
   onSelector,
-  onFixup,
 }: {
   readonly field: StudioFieldId;
   readonly selector: string;
-  readonly fixup: FieldFixup;
   readonly selectorMessages: readonly string[];
-  readonly fixupMessages: readonly string[];
   readonly onSelector: (selector: string) => void;
-  readonly onFixup: (fixup: FieldFixup) => void;
 }) {
-  const lengthError = hasIncompleteTrim(fixup) ? COPY.trimAtLeastTwo : undefined;
-
   return (
     <div id="studio-field-panel" class="layout-stack layout-stack--tight">
       <p class="ui-eyebrow">{fieldLabel(field)}</p>
@@ -322,51 +363,6 @@ function FieldFixPanel({
         />
         <FieldErrors messages={selectorMessages} />
       </label>
-      <label class="field-block" htmlFor="studio-cleanup">
-        <span class="ui-eyebrow">{COPY.cleanup}</span>
-        <select
-          id="studio-cleanup"
-          class="input"
-          value={fixup.kind}
-          onChange={(event) => {
-            const value = inputValue(event);
-            if (!isFixupKind(value)) return;
-            onFixup(fixupFromKind(value, fixup));
-          }}
-        >
-          <option value="none">{COPY.noCleanup}</option>
-          <option value="strip_html">{COPY.stripHtml}</option>
-          <option value="trim_length">{COPY.trimToLength}</option>
-          <option value="remove_affix">{COPY.removeAffix}</option>
-        </select>
-        <FieldErrors messages={fixupMessages} />
-      </label>
-      {fixup.kind === 'trim_length' ? (
-        <label class="field-block" htmlFor="studio-fixup-length">
-          <span class="ui-eyebrow">{COPY.length}</span>
-          <input
-            id="studio-fixup-length"
-            class="input input--mono"
-            type="number"
-            min={2}
-            inputMode="numeric"
-            value={fixup.length}
-            onInput={(event) => onFixup({ kind: 'trim_length', length: inputValue(event) })}
-          />
-          <FieldErrors messages={lengthError ? [lengthError] : []} />
-        </label>
-      ) : undefined}
-      {fixup.kind === 'remove_affix' ? (
-        <label class="field-block" htmlFor="studio-fixup-affix">
-          <span class="ui-eyebrow">{COPY.prefixOrSuffix}</span>
-          <input
-            id="studio-fixup-affix"
-            class="input"
-            value={fixup.text}
-            onInput={(event) => onFixup({ kind: 'remove_affix', text: inputValue(event) })}
-          />
-        </label>
-      ) : undefined}
     </div>
   );
 }
@@ -412,14 +408,10 @@ function hasSampleField(items: readonly StudioSampleItem[], field: StudioFieldId
   }
 }
 
-function fieldMessages(
-  issues: readonly StudioIssue[],
-  field: StudioFieldId,
-  control: 'selector' | 'fixup'
-): readonly string[] {
+function fieldMessages(issues: readonly StudioIssue[], field: StudioFieldId): readonly string[] {
   return messagesFor(issues, (issue) => {
     const place = issuePlace(issue.path);
-    return place.kind === 'field' && place.field === field && place.control === control;
+    return place.kind === 'field' && place.field === field;
   });
 }
 
@@ -441,55 +433,14 @@ function isHiddenIssue(issue: StudioIssue, openField: StudioFieldId | undefined)
   return true;
 }
 
-function firstFieldIssue(
-  issues: readonly StudioIssue[]
-): { readonly field: StudioFieldId; readonly control: 'selector' | 'fixup' } | undefined {
+function firstFieldIssue(issues: readonly StudioIssue[]): { readonly field: StudioFieldId } | undefined {
   for (const issue of issues) {
     const place = issuePlace(issue.path);
-    if (place.kind === 'field') return { field: place.field, control: place.control };
+    if (place.kind === 'field') return { field: place.field };
   }
   return undefined;
 }
 
-function fixupControlId(fixup: FieldFixup): string {
-  switch (fixup.kind) {
-    case 'trim_length': {
-      return 'studio-fixup-length';
-    }
-    case 'remove_affix': {
-      return 'studio-fixup-affix';
-    }
-    case 'none':
-    case 'strip_html': {
-      return 'studio-cleanup';
-    }
-  }
-}
-
-function fixupFromKind(kind: FixupKind, current: FieldFixup): FieldFixup {
-  switch (kind) {
-    case 'none': {
-      return { kind: 'none' };
-    }
-    case 'strip_html': {
-      return { kind: 'strip_html' };
-    }
-    case 'trim_length': {
-      return { kind: 'trim_length', length: current.kind === 'trim_length' ? current.length : '' };
-    }
-    case 'remove_affix': {
-      return { kind: 'remove_affix', text: current.kind === 'remove_affix' ? current.text : '' };
-    }
-  }
-}
-
-function isFixupKind(value: string): value is FixupKind {
-  for (const kind of FIXUP_KINDS) {
-    if (kind === value) return true;
-  }
-  return false;
-}
-
 function sampleKey(item: StudioSampleItem, index: number): string {
   return `${item.title}-${item.url ?? ''}-${item.publishedAt ?? ''}-${index}`;
 }
@@ -505,7 +456,7 @@ function focusElement(id: string) {
   if (typeof element.scrollIntoView === 'function') element.scrollIntoView();
 }
 
-function inputValue(event: JSX.TargetedEvent<HTMLInputElement | HTMLSelectElement>): string {
+function inputValue(event: JSX.TargetedEvent<HTMLInputElement>): string {
   return event.currentTarget.value;
 }
 
diff --git a/frontend/src/components/ResultDisplay.tsx b/frontend/src/components/ResultDisplay.tsx
index 6aa3237e..f37ba4bf 100644
--- a/frontend/src/components/ResultDisplay.tsx
+++ b/frontend/src/components/ResultDisplay.tsx
@@ -7,6 +7,7 @@ import { PreviewItem } from './PreviewItem';
 
 interface ResultDisplayProperties {
   viewModel: Extract<AppViewModel, { kind: 'result' }>;
+  studioEnabled: boolean;
   onCreateAnother: () => void;
   onRefine: () => void;
   onRetryPreview: () => void;
@@ -29,6 +30,7 @@ function PreviewSection({ ariaLabel, eyebrow, children }: PreviewSectionProperti
 
 export function ResultDisplay({
   viewModel,
+  studioEnabled,
   onCreateAnother,
   onRefine,
   onRetryPreview,
@@ -102,9 +104,11 @@ export function ResultDisplay({
             {COPY.openInFeedReader}
           </a>
         )}
-        <button type="button" class="btn btn--quiet btn--linkish" onClick={onRefine}>
-          {COPY.refineSelectors}
-        </button>
+        {studioEnabled ? (
+          <button type="button" class="btn btn--quiet btn--linkish" onClick={onRefine}>
+            {COPY.refineSelectors}
+          </button>
+        ) : undefined}
         <button type="button" class="btn btn--quiet btn--linkish" onClick={onCreateAnother}>
           {COPY.createAnother}
         </button>
diff --git a/frontend/src/feed/useFeedFlow.ts b/frontend/src/feed/useFeedFlow.ts
index 0fb8de86..cfb107cc 100644
--- a/frontend/src/feed/useFeedFlow.ts
+++ b/frontend/src/feed/useFeedFlow.ts
@@ -19,6 +19,7 @@ export interface FeedFlowDependencies {
   token: string | undefined;
   isLoading: boolean;
   feedCreationEnabled: boolean;
+  studioEnabled: boolean;
   mayCreate: (accessToken?: string) => MayCreateResult;
   saveToken: (token: string) => Promise<void>;
   clearToken: () => void;
@@ -34,6 +35,7 @@ export function useFeedFlow({
   token,
   isLoading,
   feedCreationEnabled,
+  studioEnabled,
   mayCreate,
   saveToken,
   clearToken,
@@ -203,14 +205,18 @@ export function useFeedFlow({
     navigate({ kind: 'create' }, { replace: true });
   }, [navigate, result, route]);
 
-  // Recover refine routes with no in-memory URL onto a remounted create view.
+  // Recover refine routes when studio is off or no in-memory URL onto remounted create.
   useEffect(() => {
     if (route.kind !== 'refine') return;
+    if (!studioEnabled) {
+      navigate({ kind: 'create' }, { replace: true });
+      return;
+    }
     if (inMemorySourceUrl(feedFormData.url, result?.feed.url)) return;
 
     // Do not carry a prefill URL — that would re-trigger auto-submit.
     navigate({ kind: 'create' }, { replace: true });
-  }, [feedFormData.url, navigate, result, route]);
+  }, [feedFormData.url, navigate, result, route, studioEnabled]);
 
   useEffect(() => {
     const previousKind = previousRouteKindReference.current;
@@ -317,8 +323,18 @@ export function useFeedFlow({
       navigate({ kind: 'create', prefillUrl: feedFormData.url || undefined });
     },
     onRefine: () => {
+      if (!studioEnabled) return;
       navigate({ kind: 'refine' });
     },
+    onStudioUrlChange: (nextUrl: string) => {
+      onFeedFieldChange('url', nextUrl);
+    },
+    onStudioUrlCleared: () => {
+      setFeedFormData({ url: '' });
+      clearFeedDraftState();
+      clearResult();
+      navigate({ kind: 'create' }, { replace: true });
+    },
     generateFromStudio,
     onRetryPreview: retryPreviewFetch,
     sourceUrl,
diff --git a/frontend/src/journey/copy.ts b/frontend/src/journey/copy.ts
index e9d43ef0..b3162a9b 100644
--- a/frontend/src/journey/copy.ts
+++ b/frontend/src/journey/copy.ts
@@ -73,6 +73,7 @@ export const COPY = {
   applySuggestion: 'Apply suggestion',
   saveAndGenerate: 'Save and generate feed',
   viewAsYaml: 'View as YAML',
+  yamlFragmentCaption: 'Selectors fragment — not a feeds.yml config',
   previewFetchedCaption: 'Based on the page as fetched just now',
   nativeFeedTitle: 'This site already publishes a feed.',
   fieldTitle: 'Title',
@@ -81,13 +82,5 @@ export const COPY = {
   fieldFound: (name: string) => `${name} — found`,
   fieldMissing: (name: string) => `${name} — not found`,
   selector: 'Selector',
-  cleanup: 'Cleanup',
-  noCleanup: 'None',
-  stripHtml: 'Strip HTML',
-  trimToLength: 'Trim to length',
-  removeAffix: 'Remove a fixed prefix or suffix',
-  length: 'Length',
-  prefixOrSuffix: 'Prefix or suffix',
-  trimAtLeastTwo: 'Enter 2 or more.',
   issueCount: (count: number) => (count === 1 ? '1 issue' : `${count} issues`),
 } as const;
diff --git a/frontend/src/session/useSession.ts b/frontend/src/session/useSession.ts
index 3f0f2628..2af7f7d7 100644
--- a/frontend/src/session/useSession.ts
+++ b/frontend/src/session/useSession.ts
@@ -5,6 +5,7 @@ import { useApiMetadata } from '../hooks/useApiMetadata';
 import { useAccessToken } from './accessToken';
 
 const DEFAULT_FEED_CREATION = { enabled: true, access_token_required: true };
+const isStudioEnabledByDefault = false;
 
 /** Closed gate outcome for attempting feed creation with an optional token. */
 export type MayCreateResult = 'proceed' | 'needToken' | 'disabled';
@@ -28,6 +29,7 @@ export function useSession() {
   const isLoading = tokenLoading || metadataLoading;
   const feedCreation = metadata?.instance.feed_creation ?? DEFAULT_FEED_CREATION;
   const feedCreationEnabled = feedCreation.enabled;
+  const studioEnabled = metadata?.instance.studio?.enabled ?? isStudioEnabledByDefault;
   const catalog = useCatalogEntries(metadata);
   const catalogEntries = catalog.entries;
   const featuredFeeds: CatalogEntry[] = useMemo(
@@ -54,6 +56,7 @@ export function useSession() {
     saveToken,
     clearToken,
     feedCreationEnabled,
+    studioEnabled,
     mayCreate,
   };
 }
diff --git a/frontend/src/studio/useStudio.ts b/frontend/src/studio/useStudio.ts
index 192761b0..64aa5d74 100644
--- a/frontend/src/studio/useStudio.ts
+++ b/frontend/src/studio/useStudio.ts
@@ -374,6 +374,7 @@ function assignLive(state: StudioState, live: LivePreview): StudioState {
 }
 
 function failureMessage(error: unknown): string {
-  if (isFeedCreationError(error) || error instanceof Error) return error.message;
-  return COPY.unableToCompleteCreation;
+  if (isFeedCreationError(error)) return error.message;
+  if (error instanceof Error && error.message.trim()) return error.message;
+  return COPY.createFailedTitle;
 }
diff --git a/frontend/src/styles/main.css b/frontend/src/styles/main.css
index 6171a8e6..9ad77bf8 100644
--- a/frontend/src/styles/main.css
+++ b/frontend/src/styles/main.css
@@ -572,29 +572,23 @@
   }
 }
 
-.refine-columns {
+.refine-enhance {
   display: flex;
-  flex-direction: row;
+  flex-direction: column;
   align-items: flex-start;
-  gap: var(--space-4);
-}
-
-.refine-pane {
-  flex: 1;
-  min-width: 0;
-}
-
-.refine-columns .field-help {
-  text-align: start;
+  gap: var(--space-1);
 }
 
-.refine-action {
-  width: 100%;
+.refine-enhance__label {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--space-2);
 }
 
 .refine-check {
-  justify-self: start;
   width: auto;
+  margin: 0;
 }
 
 .refine-sample-image {
@@ -620,12 +614,6 @@
   white-space: pre-wrap;
 }
 
-@media (width < 48rem) {
-  .refine-columns {
-    flex-direction: column;
-  }
-}
-
 @keyframes spin {
   to {
     transform: rotate(360deg);
diff --git a/public/openapi.yaml b/public/openapi.yaml
index b1ba6bf1..11cc72dd 100644
--- a/public/openapi.yaml
+++ b/public/openapi.yaml
@@ -64,8 +64,16 @@ paths:
                             - enabled
                             - access_token_required
                             type: object
+                          studio:
+                            properties:
+                              enabled:
+                                type: boolean
+                            required:
+                            - enabled
+                            type: object
                         required:
                         - feed_creation
+                        - studio
                         - catalog
                         type: object
                     required:
diff --git a/spec/html2rss/web/api/v1_spec.rb b/spec/html2rss/web/api/v1_spec.rb
index 6b23ee17..2eeb526e 100644
--- a/spec/html2rss/web/api/v1_spec.rb
+++ b/spec/html2rss/web/api/v1_spec.rb
@@ -193,6 +193,14 @@ def relative_feed_link_header(token)
       )
     end
 
+    it 'returns studio capability', :aggregate_failures do
+      get '/api/v1'
+
+      expect(last_response.status).to eq(200)
+      json = expect_success_response(last_response)
+      expect(json.dig('data', 'instance', 'studio')).to eq('enabled' => true)
+    end
+
     it 'returns catalog pointer metadata', :aggregate_failures do
       get '/api/v1'
 

From 0d2c8f8a84fcd12f6c99556308faa598241d3062 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 20 Sep 2026 11:20:21 +0200
Subject: [PATCH 036/108] fix(studio): prefill items selector with gem default
 then capture

Show a[href] immediately on refine mount, auto-suggest with an empty
hint so capture can determine a real selector, and overwrite the default
only while the field is untouched.
---
 frontend/src/__tests__/useStudio.test.ts | 27 +++++++++++++++++++++---
 frontend/src/studio/selectorDraft.ts     |  5 ++++-
 frontend/src/studio/useStudio.ts         |  5 ++---
 3 files changed, 30 insertions(+), 7 deletions(-)

diff --git a/frontend/src/__tests__/useStudio.test.ts b/frontend/src/__tests__/useStudio.test.ts
index 2d3ef07b..368d0fd4 100644
--- a/frontend/src/__tests__/useStudio.test.ts
+++ b/frontend/src/__tests__/useStudio.test.ts
@@ -2,6 +2,7 @@ import { describe, it, expect, beforeEach, afterEach, vi, type SpyInstance } fro
 import { renderHook, act, waitFor } from '@testing-library/preact';
 import {
   draftFromSelectors,
+  emptyDraft,
   selectorsFromDraft,
   withFieldFixup,
   withFieldSelector,
@@ -62,6 +63,10 @@ function callsTo(fetchMock: SpyInstance, suffix: string) {
 }
 
 describe('selector draft', () => {
+  it('starts the items selector at the gem default a[href]', () => {
+    expect(emptyDraft().itemsSelector).toBe('a[href]');
+  });
+
   it('round-trips field fixups and untouched keys', () => {
     const drafted = draftFromSelectors({
       items: { selector: 'article', enhance: true, order: 'reverse' },
@@ -286,10 +291,11 @@ describe('useStudio', () => {
     expect(callsTo(fetchMock, '/feeds/preview')).toHaveLength(1);
   });
 
-  it('fills an empty items selector once from suggestion and does not repeat', async () => {
+  it('starts at a[href], auto-suggests with an empty hint, then applies the determined selector', async () => {
+    const pendingSuggestion = Promise.withResolvers<Response>();
     fetchMock.mockImplementation(async (input: RequestInfo | URL, init?: RequestInit) => {
       if (fetchPath(input).endsWith('/feeds/suggest_selectors')) {
-        return Response.json(suggestionBody(true, '.post'));
+        return pendingSuggestion.promise;
       }
       if (fetchPath(input).endsWith('/feeds/preview')) {
         return Response.json({
@@ -308,7 +314,7 @@ describe('useStudio', () => {
       const selectors = selectorsFromBody(parsed);
       return Response.json(
         validateBody({
-          selectors: selectors ?? { items: { selector: '', enhance: false } },
+          selectors: selectors ?? { items: { selector: 'a[href]', enhance: false } },
           yaml: 'selectors: {}\n',
         })
       );
@@ -318,6 +324,21 @@ describe('useStudio', () => {
       useStudio({ url: pageUrl, token, validateDelayMs: 0, previewSettleMs: 60_000 })
     );
 
+    expect(result.current.state.draft.itemsSelector).toBe('a[href]');
+
+    await waitFor(() => expect(callsTo(fetchMock, '/feeds/suggest_selectors')).toHaveLength(1));
+    const suggestInput = callsTo(fetchMock, '/feeds/suggest_selectors')[0]?.[0];
+    expect(suggestInput).toBeInstanceOf(Request);
+    if (!(suggestInput instanceof Request)) return;
+    expect(JSON.parse(await suggestInput.clone().text())).toEqual({
+      url: pageUrl,
+      items_selector: '',
+    });
+
+    await act(async () => {
+      pendingSuggestion.resolve(Response.json(suggestionBody(true, '.post')));
+    });
+
     await waitFor(() => expect(result.current.state.draft.itemsSelector).toBe('.post'));
     expect(result.current.state.draft.enhance).toBe(true);
     expect(callsTo(fetchMock, '/feeds/suggest_selectors')).toHaveLength(1);
diff --git a/frontend/src/studio/selectorDraft.ts b/frontend/src/studio/selectorDraft.ts
index 1d59457d..96bca4dd 100644
--- a/frontend/src/studio/selectorDraft.ts
+++ b/frontend/src/studio/selectorDraft.ts
@@ -40,6 +40,9 @@ const AFFIX_PREFIX = '^(?:';
 const AFFIX_MARKER = ')|(?:';
 const AFFIX_SUFFIX = ')$';
 
+/** Wire spelling of Html2rss::Selectors::DEFAULT_ITEMS_SELECTOR. */
+export const DEFAULT_ITEMS_SELECTOR = 'a[href]';
+
 export function isPlainRecord(value: unknown): value is Record<string, unknown> {
   return (
     typeof value === 'object' && value instanceof Object && Object.getPrototypeOf(value) === Object.prototype
@@ -48,7 +51,7 @@ export function isPlainRecord(value: unknown): value is Record<string, unknown>
 
 export function emptyDraft(): StudioDraft {
   return {
-    itemsSelector: '',
+    itemsSelector: DEFAULT_ITEMS_SELECTOR,
     enhance: false,
     fields: {
       title: blankField(),
diff --git a/frontend/src/studio/useStudio.ts b/frontend/src/studio/useStudio.ts
index 64aa5d74..90b98b28 100644
--- a/frontend/src/studio/useStudio.ts
+++ b/frontend/src/studio/useStudio.ts
@@ -116,7 +116,7 @@ export function useStudio({
       const evidence = await suggestStudioSelectors(
         token,
         url,
-        stateReference.current.draft.itemsSelector,
+        '',
         signal
       );
       if (signal.aborted || suggestRequestReference.current !== requestId) return;
@@ -329,8 +329,7 @@ function prefillFromSuggestion(
   isItemsTouched: boolean,
   isEnhanceTouched: boolean
 ): StudioDraft {
-  const canFillItems =
-    !isItemsTouched && draft.itemsSelector.trim().length === 0 && suggestion.itemsSelector.length > 0;
+  const canFillItems = !isItemsTouched && suggestion.itemsSelector.length > 0;
   const itemsSelector = (canFillItems ? suggestion : draft).itemsSelector;
   const enhance = (isEnhanceTouched ? draft : suggestion).enhance;
   if (itemsSelector === draft.itemsSelector && enhance === draft.enhance) return draft;

From 7825dd19ed984c14580be697c3202f0dcf75516d Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 20 Sep 2026 11:20:52 +0200
Subject: [PATCH 037/108] test(studio): assert items selector shows default
 then determined

Lock the visible refine input path: a[href] before suggest resolves,
determined value after, and a non-empty e2e refine field.
---
 frontend/e2e/smoke.spec.ts                   |  1 +
 frontend/src/__tests__/ConfigStudio.test.tsx | 26 ++++++++++++++++++++
 2 files changed, 27 insertions(+)

diff --git a/frontend/e2e/smoke.spec.ts b/frontend/e2e/smoke.spec.ts
index 2e9f3c98..bc15d44d 100644
--- a/frontend/e2e/smoke.spec.ts
+++ b/frontend/e2e/smoke.spec.ts
@@ -264,6 +264,7 @@ test.describe('frontend smoke', () => {
     await page.getByRole('button', { name: COPY.refineSelectors }).click();
     await expect(page).toHaveURL(/\/#\/refine$/);
     await expect(page.getByLabel(COPY.itemsSelector)).toBeVisible();
+    await expect(page.getByLabel(COPY.itemsSelector)).not.toHaveValue('');
     await expect(page.getByRole('button', { name: COPY.fieldMissing(COPY.fieldTitle) })).toBeVisible();
     await expect(page.locator('textarea')).toHaveCount(0);
     await expect(page.getByRole('combobox')).toHaveCount(0);
diff --git a/frontend/src/__tests__/ConfigStudio.test.tsx b/frontend/src/__tests__/ConfigStudio.test.tsx
index 5c45a350..0bdeccc9 100644
--- a/frontend/src/__tests__/ConfigStudio.test.tsx
+++ b/frontend/src/__tests__/ConfigStudio.test.tsx
@@ -140,6 +140,32 @@ describe('ConfigStudio', () => {
     expect(onUrlCleared).toHaveBeenCalledTimes(1);
   });
 
+  it('shows a[href] immediately then the determined selector once suggest returns', async () => {
+    echoValidate();
+    const pendingSuggestion = Promise.withResolvers<Response>();
+    server.use(http.post('/api/v1/feeds/suggest_selectors', () => pendingSuggestion.promise));
+
+    renderStudio();
+
+    const items = screen.getByLabelText(COPY.itemsSelector);
+    expect(items).toHaveValue('a[href]');
+
+    pendingSuggestion.resolve(
+      HttpResponse.json({
+        success: true,
+        data: {
+          selectors: { items: { selector: '.post', enhance: true } },
+          segment_strategy: 'list',
+          admission_drops: { chrome: 0 },
+          enhance: true,
+        },
+      })
+    );
+
+    await waitFor(() => expect(items).toHaveValue('.post'));
+    expect(screen.getByLabelText(COPY.enhanceItems)).toBeChecked();
+  });
+
   it('checks enhance from suggestion and prefills an empty items selector', async () => {
     echoValidate();
     server.use(

From 4f56b8689a5b466363c86fab7cbf7c0fe542f2cd Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 20 Sep 2026 11:21:26 +0200
Subject: [PATCH 038/108] style(studio): format empty auto-suggest hint call

---
 frontend/src/studio/useStudio.ts | 7 +------
 1 file changed, 1 insertion(+), 6 deletions(-)

diff --git a/frontend/src/studio/useStudio.ts b/frontend/src/studio/useStudio.ts
index 90b98b28..c51378dd 100644
--- a/frontend/src/studio/useStudio.ts
+++ b/frontend/src/studio/useStudio.ts
@@ -113,12 +113,7 @@ export function useStudio({
 
   async function loadEnhanceEvidence(requestId: number, signal: AbortSignal) {
     try {
-      const evidence = await suggestStudioSelectors(
-        token,
-        url,
-        '',
-        signal
-      );
+      const evidence = await suggestStudioSelectors(token, url, '', signal);
       if (signal.aborted || suggestRequestReference.current !== requestId) return;
       const next = prefillFromSuggestion(
         stateReference.current.draft,

From 203f0f4bb3cf5b42fd6a6bc5f362da58c2ef736a Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 20 Sep 2026 11:38:17 +0200
Subject: [PATCH 039/108] fix(studio): omit disabled enhance from selectors

---
 frontend/e2e/smoke.spec.ts                   | 6 +++---
 frontend/src/__tests__/ConfigStudio.test.tsx | 2 +-
 frontend/src/__tests__/useStudio.test.ts     | 2 +-
 frontend/src/studio/selectorDraft.ts         | 3 ++-
 4 files changed, 7 insertions(+), 6 deletions(-)

diff --git a/frontend/e2e/smoke.spec.ts b/frontend/e2e/smoke.spec.ts
index bc15d44d..9aa1ab6b 100644
--- a/frontend/e2e/smoke.spec.ts
+++ b/frontend/e2e/smoke.spec.ts
@@ -228,14 +228,14 @@ test.describe('frontend smoke', () => {
       success: true,
       data: {
         report: { success: true, issues: [] },
-        selectors: { items: { selector: 'article', enhance: false } },
-        yaml: 'selectors:\n  items:\n    selector: article\n    enhance: false\n',
+        selectors: { items: { selector: 'article' } },
+        yaml: 'selectors:\n  items:\n    selector: article\n',
       },
     });
     await fulfillJson(page, API_SUGGEST, {
       success: true,
       data: {
-        selectors: { items: { selector: 'article', enhance: false } },
+        selectors: { items: { selector: 'article' } },
         segment_strategy: 'list',
         admission_drops: { chrome: 0 },
         enhance: false,
diff --git a/frontend/src/__tests__/ConfigStudio.test.tsx b/frontend/src/__tests__/ConfigStudio.test.tsx
index 0bdeccc9..05fb3009 100644
--- a/frontend/src/__tests__/ConfigStudio.test.tsx
+++ b/frontend/src/__tests__/ConfigStudio.test.tsx
@@ -398,6 +398,6 @@ describe('ConfigStudio', () => {
     fireEvent.click(save);
 
     await waitFor(() => expect(onGenerate).toHaveBeenCalled());
-    expect(onGenerate.mock.calls[0]?.[0]).toMatchObject({ items: { selector: 'article', enhance: false } });
+    expect(onGenerate.mock.calls[0]?.[0]).toEqual({ items: { selector: 'article' } });
   });
 });
diff --git a/frontend/src/__tests__/useStudio.test.ts b/frontend/src/__tests__/useStudio.test.ts
index 368d0fd4..b2f1f395 100644
--- a/frontend/src/__tests__/useStudio.test.ts
+++ b/frontend/src/__tests__/useStudio.test.ts
@@ -159,7 +159,7 @@ describe('useStudio', () => {
     expect(fetchPath(validateInput)).toBe('/api/v1/feeds/validate');
     expect(validateInput.headers.get('Authorization')).toBe(`Bearer ${token}`);
     expect(JSON.parse(await validateInput.clone().text())).toEqual({
-      selectors: { items: { selector: 'article', enhance: false } },
+      selectors: { items: { selector: 'article' } },
     });
 
     const state = result.current.state;
diff --git a/frontend/src/studio/selectorDraft.ts b/frontend/src/studio/selectorDraft.ts
index 96bca4dd..9cbf01ec 100644
--- a/frontend/src/studio/selectorDraft.ts
+++ b/frontend/src/studio/selectorDraft.ts
@@ -65,7 +65,8 @@ export function emptyDraft(): StudioDraft {
 
 export function selectorsFromDraft(draft: StudioDraft): Record<string, unknown> {
   const selectors = withoutKeys(draft.preserved, ['items', 'title', 'url', 'published_at']);
-  const items: Record<string, unknown> = { ...draft.itemsPreserved, enhance: draft.enhance };
+  const items: Record<string, unknown> = { ...draft.itemsPreserved };
+  if (draft.enhance) items.enhance = true;
   if (draft.itemsSelector.length > 0) items.selector = draft.itemsSelector;
   selectors.items = items;
 

From 57a2fa4b9b12d2f37306f95051fb41855c959efc Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 20 Sep 2026 11:38:21 +0200
Subject: [PATCH 040/108] refactor(studio): centralize request handling

---
 app/web/api/v1/preview_feed.rb      | 42 +------------------
 app/web/api/v1/studio_request.rb    | 64 +++++++++++++++++++++++++++++
 app/web/api/v1/suggest_selectors.rb | 43 +------------------
 app/web/api/v1/validate_config.rb   | 41 +-----------------
 4 files changed, 70 insertions(+), 120 deletions(-)
 create mode 100644 app/web/api/v1/studio_request.rb

diff --git a/app/web/api/v1/preview_feed.rb b/app/web/api/v1/preview_feed.rb
index 4c6aa201..72b38062 100644
--- a/app/web/api/v1/preview_feed.rb
+++ b/app/web/api/v1/preview_feed.rb
@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require 'json'
 require 'nokogiri'
 require 'rss'
 
@@ -19,8 +18,8 @@ class << self
             # @param request [Rack::Request]
             # @return [Hash{Symbol=>Object}]
             def call(request)
-              account = live_account(request)
-              body = json_object(request)
+              account = StudioRequest.ensure_allowed!(request, live_fetch: true)
+              body = StudioRequest.json_object(request)
               url = allowed_url(body['url'], account)
               result = Html2rss.test(preview_config(url, body['selectors']), min_items: 1)
               Response.success(response: request.response, data: preview_fields(result))
@@ -28,43 +27,6 @@ def call(request)
 
             private
 
-            # Authenticates first so an anonymous caller cannot probe flag state.
-            #
-            # @param request [Rack::Request]
-            # @return [Hash]
-            def live_account(request)
-              account = Auth.authenticate(request)
-              raise UnauthorizedError, 'Authentication required' unless account
-              raise ForbiddenError, 'Studio is disabled' unless Flags.studio_enabled?
-              raise AutoSourceDisabledError unless Flags.auto_source_enabled?
-
-              account
-            end
-
-            # @param request [Rack::Request]
-            # @return [Hash]
-            def json_object(request)
-              raw = read_body(request)
-              return {} if raw.strip.empty?
-
-              parsed = JSON.parse(raw)
-              raise BadRequestError, 'Invalid JSON payload' unless parsed.is_a?(Hash)
-
-              parsed
-            rescue JSON::ParserError
-              raise BadRequestError, 'Invalid JSON payload'
-            end
-
-            def read_body(request)
-              limit = CreateFeed::MAX_BODY_BYTES
-              raise BadRequestError, 'Payload too large' if request.content_length.to_i > limit
-
-              request.body.read(limit + 1).to_s.tap do |raw|
-                request.body.rewind
-                raise BadRequestError, 'Payload too large' if raw.bytesize > limit
-              end
-            end
-
             # @param raw_url [String, nil]
             # @param account [Hash]
             # @return [String]
diff --git a/app/web/api/v1/studio_request.rb b/app/web/api/v1/studio_request.rb
new file mode 100644
index 00000000..4103cc52
--- /dev/null
+++ b/app/web/api/v1/studio_request.rb
@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Html2rss
+  module Web
+    module Api
+      module V1
+        ##
+        # Shared authentication, feature gating, and JSON parsing for studio requests.
+        module StudioRequest
+          class << self
+            ##
+            # Authenticates before checking feature flags so anonymous callers
+            # cannot discover disabled studio capabilities.
+            #
+            # @param request [Rack::Request]
+            # @param live_fetch [Boolean] whether the request needs automatic source fetching
+            # @return [Hash] the authenticated account
+            def ensure_allowed!(request, live_fetch: false)
+              account = Auth.authenticate(request)
+              raise UnauthorizedError, 'Authentication required' unless account
+              raise ForbiddenError, 'Studio is disabled' unless Flags.studio_enabled?
+              raise AutoSourceDisabledError if live_fetch && !Flags.auto_source_enabled?
+
+              account
+            end
+
+            ##
+            # Parses a size-bounded JSON request body as an object.
+            #
+            # @param request [Rack::Request]
+            # @return [Hash]
+            def json_object(request)
+              raw = read_body(request)
+              return {} if raw.strip.empty?
+
+              parsed = JSON.parse(raw)
+              raise BadRequestError, 'Invalid JSON payload' unless parsed.is_a?(Hash)
+
+              parsed
+            rescue JSON::ParserError
+              raise BadRequestError, 'Invalid JSON payload'
+            end
+
+            private
+
+            # @param request [Rack::Request]
+            # @return [String]
+            def read_body(request)
+              limit = CreateFeed::MAX_BODY_BYTES
+              raise BadRequestError, 'Payload too large' if request.content_length.to_i > limit
+
+              request.body.read(limit + 1).to_s.tap do |raw|
+                request.body.rewind
+                raise BadRequestError, 'Payload too large' if raw.bytesize > limit
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end
diff --git a/app/web/api/v1/suggest_selectors.rb b/app/web/api/v1/suggest_selectors.rb
index de17f53c..9121896e 100644
--- a/app/web/api/v1/suggest_selectors.rb
+++ b/app/web/api/v1/suggest_selectors.rb
@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'json'
-
 module Html2rss
   module Web
     module Api
@@ -20,8 +18,8 @@ class << self
             # @param request [Rack::Request]
             # @return [Hash{Symbol=>Object}]
             def call(request)
-              account = live_account(request)
-              body = json_object(request)
+              account = StudioRequest.ensure_allowed!(request, live_fetch: true)
+              body = StudioRequest.json_object(request)
               captured = Html2rss.capture(
                 allowed_url(body['url'], account),
                 strategy: :auto,
@@ -32,43 +30,6 @@ def call(request)
 
             private
 
-            # Authenticates first so an anonymous caller cannot probe flag state.
-            #
-            # @param request [Rack::Request]
-            # @return [Hash]
-            def live_account(request)
-              account = Auth.authenticate(request)
-              raise UnauthorizedError, 'Authentication required' unless account
-              raise ForbiddenError, 'Studio is disabled' unless Flags.studio_enabled?
-              raise AutoSourceDisabledError unless Flags.auto_source_enabled?
-
-              account
-            end
-
-            # @param request [Rack::Request]
-            # @return [Hash]
-            def json_object(request)
-              raw = read_body(request)
-              return {} if raw.strip.empty?
-
-              parsed = JSON.parse(raw)
-              raise BadRequestError, 'Invalid JSON payload' unless parsed.is_a?(Hash)
-
-              parsed
-            rescue JSON::ParserError
-              raise BadRequestError, 'Invalid JSON payload'
-            end
-
-            def read_body(request)
-              limit = CreateFeed::MAX_BODY_BYTES
-              raise BadRequestError, 'Payload too large' if request.content_length.to_i > limit
-
-              request.body.read(limit + 1).to_s.tap do |raw|
-                request.body.rewind
-                raise BadRequestError, 'Payload too large' if raw.bytesize > limit
-              end
-            end
-
             # @param raw_url [String, nil]
             # @param account [Hash]
             # @return [String]
diff --git a/app/web/api/v1/validate_config.rb b/app/web/api/v1/validate_config.rb
index 0a6bbf90..d7af6c52 100644
--- a/app/web/api/v1/validate_config.rb
+++ b/app/web/api/v1/validate_config.rb
@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'json'
-
 module Html2rss
   module Web
     module Api
@@ -20,49 +18,14 @@ class << self
             # @param request [Rack::Request]
             # @return [Hash{Symbol=>Object}]
             def call(request)
-              ensure_allowed!(request)
-              body = json_object(request)
+              StudioRequest.ensure_allowed!(request)
+              body = StudioRequest.json_object(request)
               report, selectors = assess(body)
               Response.success(response: request.response, data: payload(report, selectors))
             end
 
             private
 
-            # Authenticates first so an anonymous caller cannot probe flag state.
-            #
-            # @param request [Rack::Request]
-            # @return [void]
-            def ensure_allowed!(request)
-              raise UnauthorizedError, 'Authentication required' unless Auth.authenticate(request)
-              raise ForbiddenError, 'Studio is disabled' unless Flags.studio_enabled?
-            end
-
-            # @param request [Rack::Request]
-            # @return [Hash]
-            def json_object(request)
-              raw = read_body(request)
-              return {} if raw.strip.empty?
-
-              parsed = JSON.parse(raw)
-              raise BadRequestError, 'Invalid JSON payload' unless parsed.is_a?(Hash)
-
-              parsed
-            rescue JSON::ParserError
-              raise BadRequestError, 'Invalid JSON payload'
-            end
-
-            # @param request [Rack::Request]
-            # @return [String]
-            def read_body(request)
-              limit = CreateFeed::MAX_BODY_BYTES
-              raise BadRequestError, 'Payload too large' if request.content_length.to_i > limit
-
-              request.body.read(limit + 1).to_s.tap do |raw|
-                request.body.rewind
-                raise BadRequestError, 'Payload too large' if raw.bytesize > limit
-              end
-            end
-
             # @param body [Hash]
             # @return [Array(Html2rss::Config::ValidationReport, Hash, nil)]
             def assess(body)

From 0a05c8492f7708d9ef1ca55b180f6c4254f661b9 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 20 Sep 2026 11:38:24 +0200
Subject: [PATCH 041/108] feat(studio): weight live fetch rate limits

---
 app/web/request/rate_limiter.rb        | 41 +++++++++++++++++++++-----
 docs/README.md                         |  2 ++
 spec/html2rss/web/rate_limiter_spec.rb | 15 ++++++++++
 3 files changed, 51 insertions(+), 7 deletions(-)

diff --git a/app/web/request/rate_limiter.rb b/app/web/request/rate_limiter.rb
index 28fb06a8..94bab2e9 100644
--- a/app/web/request/rate_limiter.rb
+++ b/app/web/request/rate_limiter.rb
@@ -10,6 +10,12 @@ module Web
     # Rack middleware providing IP-based rate limiting with fiber-native tracking,
     # automated pruning, and standardized 429 error formatting.
     class RateLimiter
+      LIVE_FETCH_PATH_COSTS = {
+        '/api/v1/feeds/preview' => 5,
+        '/api/v1/feeds/suggest_selectors' => 5
+      }.freeze
+      private_constant :LIVE_FETCH_PATH_COSTS
+
       ##
       # Encapsulates timestamp tracking and rate limit logic for a single client IP.
       class RequestTrack
@@ -26,8 +32,9 @@ def initialize
         # @param now [Integer]
         # @param window_seconds [Integer]
         # @param max_requests [Integer]
+        # @param cost [Integer] slots consumed by this request
         # @return [Array<(Boolean, Integer)>] limit exceeded flag and retry_after seconds.
-        def record_and_check_limit(now, window_seconds, max_requests)
+        def record_and_check_limit(now, window_seconds, max_requests, cost: 1)
           window_start = now - window_seconds
           @timestamps.reject! { |t| t < window_start }
 
@@ -36,7 +43,7 @@ def record_and_check_limit(now, window_seconds, max_requests)
             retry_after = [1, oldest + window_seconds - now].max
             [true, retry_after]
           else
-            @timestamps << now
+            @timestamps.concat([now] * cost)
             [false, 0]
           end
         end
@@ -80,16 +87,16 @@ def call(env)
         limit_exceeded, retry_after = track.record_and_check_limit(
           now,
           Flags.rate_limit_window_seconds,
-          Flags.rate_limit_max_requests
+          Flags.rate_limit_max_requests,
+          cost: request_cost(path)
         )
 
         if limit_exceeded
           SecurityLogger.log_rate_limit_exceeded(client_key, path, Flags.rate_limit_max_requests)
 
-          # Ensure feed endpoints get feed-formatted errors
-          if path.start_with?('/api/v1/feeds/') || !path.start_with?('/api/v1/')
-            env[RequestTarget::ENV_KEY] = RequestTarget::FEED
-          end
+          # Ensure token and public feed endpoints get feed-formatted errors.
+          # Studio POSTs remain API-shaped even though they share the feeds prefix.
+          env[RequestTarget::ENV_KEY] = RequestTarget::FEED if feed_response_path?(path)
 
           error = TooManyRequestsError.new
           response = Rack::Response.new
@@ -106,6 +113,26 @@ def call(env)
 
       private
 
+      # @param path [String]
+      # @return [Integer]
+      def request_cost(path)
+        LIVE_FETCH_PATH_COSTS.fetch(path, 1)
+      end
+
+      # @param path [String]
+      # @return [Boolean]
+      def studio_path?(path)
+        LIVE_FETCH_PATH_COSTS.key?(path) || path == '/api/v1/feeds/validate'
+      end
+
+      # @param path [String]
+      # @return [Boolean]
+      def feed_response_path?(path)
+        return true unless path.start_with?('/api/v1/')
+
+        path.start_with?('/api/v1/feeds/') && !studio_path?(path)
+      end
+
       # Bypasses rate limiting for root, static assets, and health checks.
       #
       # @param path [String]
diff --git a/docs/README.md b/docs/README.md
index 3e007cd5..ed3bec3b 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -211,6 +211,8 @@ Rules:
 
 `STUDIO_ENABLED=true` exposes the config refinement studio: `POST /api/v1/feeds/validate`, `POST /api/v1/feeds/preview`, and `POST /api/v1/feeds/suggest_selectors`. All three require a valid access token and return `403 Studio is disabled` when the flag is off. `POST /api/v1/feeds` returns the same `403` when the body carries a `selectors` object, because those selectors are studio output; a body without `selectors` stays the automatic path and keeps working with the flag off. `preview` and `suggest_selectors` additionally need `AUTO_SOURCE_ENABLED=true` because they fetch the caller's URL live, and they only accept URLs the caller's account is allowed to reach. `GET /api/v1` advertises `instance.studio.enabled` so the SPA can hide Refine and bounce `#/refine` when the flag is off. Leave the flag off in production unless you intend to let token holders run live extraction against arbitrary allowed URLs.
 
+Rate limiting still uses the shared `RATE_LIMIT_MAX_REQUESTS` budget over `RATE_LIMIT_WINDOW_SECONDS`, but each live-fetch studio request to `preview` or `suggest_selectors` consumes five request slots. This fixed weighting protects the more expensive HTTP/browser extraction paths without adding another deployment flag.
+
 ---
 
 ## Observability Contract
diff --git a/spec/html2rss/web/rate_limiter_spec.rb b/spec/html2rss/web/rate_limiter_spec.rb
index f7cffc87..1e1b0177 100644
--- a/spec/html2rss/web/rate_limiter_spec.rb
+++ b/spec/html2rss/web/rate_limiter_spec.rb
@@ -38,6 +38,21 @@
     expect(body.dig('error', 'code')).to eq('TOO_MANY_REQUESTS')
   end
 
+  %w[preview suggest_selectors].each do |endpoint|
+    it "weights #{endpoint} and keeps its 429 response API-shaped", :aggregate_failures do
+      allow(Html2rss::Web::Flags).to receive(:rate_limit_max_requests).and_return(10)
+
+      2.times do
+        expect(request_builder.post("/api/v1/feeds/#{endpoint}").status).to eq(200)
+      end
+
+      response = request_builder.post("/api/v1/feeds/#{endpoint}")
+      expect(response.status).to eq(429)
+      expect(response['Content-Type']).to eq('application/json')
+      expect(JSON.parse(response.body).dig('error', 'code')).to eq('TOO_MANY_REQUESTS')
+    end
+  end
+
   it 'bypasses rate limiting for health check routes' do
     4.times do
       response = request_builder.get('/api/v1/health')

From 4fc7bc45fe0d0350d4c3e3e5258bb75d17596abb Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 20 Sep 2026 11:42:24 +0200
Subject: [PATCH 042/108] test(studio): match compact selector payload

---
 frontend/src/__tests__/App.contract.test.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/frontend/src/__tests__/App.contract.test.tsx b/frontend/src/__tests__/App.contract.test.tsx
index a4cdb8b8..76461ec5 100644
--- a/frontend/src/__tests__/App.contract.test.tsx
+++ b/frontend/src/__tests__/App.contract.test.tsx
@@ -221,7 +221,7 @@ describe('App contract', () => {
     expect(bodies).toHaveLength(2);
     expect(bodies[1]).toMatchObject({
       url: 'https://example.com/articles',
-      selectors: { items: { selector: 'article', enhance: false } },
+      selectors: { items: { selector: 'article' } },
     });
     fetchSpy.mockRestore();
   });

From 53a8d39a5934290ed73dacb5d386d7bf05ef29de Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 20 Sep 2026 11:44:09 +0200
Subject: [PATCH 043/108] fix(openapi): stamp closed studio selector schemas

Replace example-inferred items-only hulls with RefinedSelectorsDocument and PreviewSampleItem so the SPA client matches the allowlisted refine payload.
---
 frontend/src/api/generated/index.ts           |   2 +-
 frontend/src/api/generated/types.gen.ts       |  71 ++++----
 frontend/src/api/http/feeds.ts                |  32 ++--
 public/openapi.yaml                           | 158 +++++++++---------
 spec/html2rss/web/api/v1_spec.rb              |  30 +++-
 spec/support/openapi.rb                       | 118 +++++++++++++
 spec/support/openapi_runtime_contract_spec.rb | 107 ++++++++++++
 7 files changed, 384 insertions(+), 134 deletions(-)
 create mode 100644 spec/support/openapi_runtime_contract_spec.rb

diff --git a/frontend/src/api/generated/index.ts b/frontend/src/api/generated/index.ts
index 4d175972..fcaa243a 100644
--- a/frontend/src/api/generated/index.ts
+++ b/frontend/src/api/generated/index.ts
@@ -1,4 +1,4 @@
 // This file is auto-generated by @hey-api/openapi-ts
 
 export { createFeed, getApiMetadata, getConfigCatalog, getHealthStatus, getLivenessProbe, getReadinessProbe, listStrategies, type Options, optionsConfigCatalog, previewFeed, renderFeedByToken, suggestSelectors, validateFeedConfig } from './sdk.gen';
-export type { ClientOptions, CreateFeedData, CreateFeedError, CreateFeedErrors, CreateFeedResponse, CreateFeedResponses, GetApiMetadataData, GetApiMetadataResponse, GetApiMetadataResponses, GetConfigCatalogData, GetConfigCatalogError, GetConfigCatalogErrors, GetConfigCatalogResponse, GetConfigCatalogResponses, GetHealthStatusData, GetHealthStatusError, GetHealthStatusErrors, GetHealthStatusResponse, GetHealthStatusResponses, GetLivenessProbeData, GetLivenessProbeResponse, GetLivenessProbeResponses, GetReadinessProbeData, GetReadinessProbeResponse, GetReadinessProbeResponses, ListStrategiesData, ListStrategiesResponse, ListStrategiesResponses, OptionsConfigCatalogData, OptionsConfigCatalogResponse, OptionsConfigCatalogResponses, PreviewFeedData, PreviewFeedResponse, PreviewFeedResponses, RefinedSelectorKey, RenderFeedByTokenData, RenderFeedByTokenError, RenderFeedByTokenErrors, RenderFeedByTokenResponse, RenderFeedByTokenResponses, SuggestSelectorsData, SuggestSelectorsResponse, SuggestSelectorsResponses, ValidateFeedConfigData, ValidateFeedConfigError, ValidateFeedConfigErrors, ValidateFeedConfigResponse, ValidateFeedConfigResponses } from './types.gen';
+export type { ClientOptions, CreateFeedData, CreateFeedError, CreateFeedErrors, CreateFeedResponse, CreateFeedResponses, GetApiMetadataData, GetApiMetadataResponse, GetApiMetadataResponses, GetConfigCatalogData, GetConfigCatalogError, GetConfigCatalogErrors, GetConfigCatalogResponse, GetConfigCatalogResponses, GetHealthStatusData, GetHealthStatusError, GetHealthStatusErrors, GetHealthStatusResponse, GetHealthStatusResponses, GetLivenessProbeData, GetLivenessProbeResponse, GetLivenessProbeResponses, GetReadinessProbeData, GetReadinessProbeResponse, GetReadinessProbeResponses, ListStrategiesData, ListStrategiesResponse, ListStrategiesResponses, OptionsConfigCatalogData, OptionsConfigCatalogResponse, OptionsConfigCatalogResponses, PreviewFeedData, PreviewFeedResponse, PreviewFeedResponses, PreviewSampleItem, RefinedSelectorKey, RefinedSelectorsDocument, RenderFeedByTokenData, RenderFeedByTokenError, RenderFeedByTokenErrors, RenderFeedByTokenResponse, RenderFeedByTokenResponses, SuggestSelectorsData, SuggestSelectorsResponse, SuggestSelectorsResponses, ValidateFeedConfigData, ValidateFeedConfigError, ValidateFeedConfigErrors, ValidateFeedConfigResponse, ValidateFeedConfigResponses } from './types.gen';
diff --git a/frontend/src/api/generated/types.gen.ts b/frontend/src/api/generated/types.gen.ts
index 8a6e7c28..b623052a 100644
--- a/frontend/src/api/generated/types.gen.ts
+++ b/frontend/src/api/generated/types.gen.ts
@@ -9,6 +9,38 @@ export type ClientOptions = {
  */
 export type RefinedSelectorKey = 'selectors';
 
+/**
+ * Allowlisted selectors document for create, validate, and preview.
+ */
+export type RefinedSelectorsDocument = {
+  items: {
+    selector: string;
+    enhance?: boolean;
+  };
+  title?: {
+    selector: string;
+    extractor: 'text';
+  };
+  url?: {
+    selector: string;
+    extractor: 'href';
+  };
+  published_at?: {
+    selector: string;
+    extractor: 'text';
+  };
+};
+
+/**
+ * One preview meadow row returned by POST /feeds/preview.
+ */
+export type PreviewSampleItem = {
+  title: string;
+  url?: string | null;
+  published_at?: string | null;
+  image?: string | null;
+};
+
 export type GetApiMetadataData = {
   body?: never;
   path?: never;
@@ -158,12 +190,7 @@ export type OptionsConfigCatalogResponse = OptionsConfigCatalogResponses[keyof O
 export type CreateFeedData = {
   body?: {
     name?: string;
-    selectors?: {
-      items: {
-        enhance: boolean;
-        selector: string;
-      };
-    };
+    selectors?: RefinedSelectorsDocument;
     url: string;
   };
   headers: {
@@ -263,11 +290,7 @@ export type CreateFeedResponse = CreateFeedResponses[keyof CreateFeedResponses];
 
 export type PreviewFeedData = {
   body?: {
-    selectors: {
-      items: {
-        selector: string;
-      };
-    };
+    selectors: RefinedSelectorsDocument;
     url: string;
   };
   headers: {
@@ -292,10 +315,7 @@ export type PreviewFeedResponses = {
         };
         warnings: Array<string>;
       } | null;
-      sample_items: Array<{
-        image?: string | null;
-        title: string;
-      }>;
+      sample_items: Array<PreviewSampleItem>;
       validation_issues: Array<unknown>;
     };
     success: boolean;
@@ -328,12 +348,7 @@ export type SuggestSelectorsResponses = {
       };
       enhance: boolean;
       segment_strategy: string;
-      selectors: {
-        items: {
-          enhance: boolean;
-          selector: string;
-        };
-      };
+      selectors: RefinedSelectorsDocument;
     };
     success: boolean;
   };
@@ -343,12 +358,7 @@ export type SuggestSelectorsResponse = SuggestSelectorsResponses[keyof SuggestSe
 
 export type ValidateFeedConfigData = {
   body?: {
-    selectors?: {
-      items: {
-        enhance: boolean;
-        selector: string;
-      };
-    };
+    selectors?: RefinedSelectorsDocument;
     yaml?: string;
   };
   headers: {
@@ -414,12 +424,7 @@ export type ValidateFeedConfigResponses = {
         }>;
         success: boolean;
       };
-      selectors: {
-        items: {
-          enhance: boolean;
-          selector: string;
-        };
-      } | null;
+      selectors: RefinedSelectorsDocument | null;
       yaml: string | null;
     };
     success: boolean;
diff --git a/frontend/src/api/http/feeds.ts b/frontend/src/api/http/feeds.ts
index b2199cfc..6450ea21 100644
--- a/frontend/src/api/http/feeds.ts
+++ b/frontend/src/api/http/feeds.ts
@@ -2,25 +2,17 @@ import { client } from '../generated/client.gen';
 import type {
   CreateFeedData,
   PreviewFeedData,
+  RefinedSelectorsDocument,
   SuggestSelectorsData,
   ValidateFeedConfigData,
 } from '../generated/types.gen';
 import { isAbortError } from '../../feeds/feedPreviewClient';
 import { jsonBaseUrl, unwrap, type HttpEnvelope } from './client';
 
-type CreateFeedWrite = Omit<NonNullable<CreateFeedData['body']>, 'selectors'> & {
-  readonly selectors?: Record<string, unknown>;
-};
-
-type PreviewFeedWrite = Omit<NonNullable<PreviewFeedData['body']>, 'selectors'> & {
-  readonly selectors: Record<string, unknown>;
-};
-
-type SuggestSelectorsWrite = NonNullable<SuggestSelectorsData['body']>;
-
-type ValidateFeedWrite = Omit<NonNullable<ValidateFeedConfigData['body']>, 'selectors'> & {
-  readonly selectors: Record<string, unknown>;
-};
+type CreateFeedBody = NonNullable<CreateFeedData['body']>;
+type PreviewFeedBody = NonNullable<PreviewFeedData['body']>;
+type SuggestSelectorsBody = NonNullable<SuggestSelectorsData['body']>;
+type ValidateFeedBody = NonNullable<ValidateFeedConfigData['body']>;
 
 const FEED_WRITE_URL = {
   create: '/feeds',
@@ -63,28 +55,28 @@ async function jsonWrite(
 export function postCreateFeed(
   url: string,
   token: string,
-  selectors?: Record<string, unknown>
+  selectors?: RefinedSelectorsDocument
 ): Promise<HttpEnvelope> {
-  const body: CreateFeedWrite = selectors ? { url, selectors } : { url };
+  const body: CreateFeedBody = selectors ? { url, selectors } : { url };
   return jsonWrite(FEED_WRITE_URL.create, token, body);
 }
 
 export function postValidateFeed(
   token: string,
-  selectors: Record<string, unknown>,
+  selectors: RefinedSelectorsDocument,
   signal?: AbortSignal
 ): Promise<HttpEnvelope> {
-  const body: ValidateFeedWrite = { selectors };
+  const body: ValidateFeedBody = { selectors };
   return jsonWrite(FEED_WRITE_URL.validate, token, body, signal);
 }
 
 export function postPreviewFeed(
   token: string,
   url: string,
-  selectors: Record<string, unknown>,
+  selectors: RefinedSelectorsDocument,
   signal?: AbortSignal
 ): Promise<HttpEnvelope> {
-  const body: PreviewFeedWrite = { url, selectors };
+  const body: PreviewFeedBody = { url, selectors };
   return jsonWrite(FEED_WRITE_URL.preview, token, body, signal);
 }
 
@@ -94,6 +86,6 @@ export function postSuggestSelectors(
   itemsSelector: string,
   signal?: AbortSignal
 ): Promise<HttpEnvelope> {
-  const body: SuggestSelectorsWrite = { url, items_selector: itemsSelector };
+  const body: SuggestSelectorsBody = { url, items_selector: itemsSelector };
   return jsonWrite(FEED_WRITE_URL.suggest, token, body, signal);
 }
diff --git a/public/openapi.yaml b/public/openapi.yaml
index 11cc72dd..8896f901 100644
--- a/public/openapi.yaml
+++ b/public/openapi.yaml
@@ -332,20 +332,7 @@ paths:
                 name:
                   type: string
                 selectors:
-                  properties:
-                    items:
-                      properties:
-                        enhance:
-                          type: boolean
-                        selector:
-                          type: string
-                      required:
-                      - selector
-                      - enhance
-                      type: object
-                  required:
-                  - items
-                  type: object
+                  "$ref": "#/components/schemas/RefinedSelectorsDocument"
                 url:
                   type: string
               required:
@@ -568,17 +555,7 @@ paths:
             schema:
               properties:
                 selectors:
-                  properties:
-                    items:
-                      properties:
-                        selector:
-                          type: string
-                      required:
-                      - selector
-                      type: object
-                  required:
-                  - items
-                  type: object
+                  "$ref": "#/components/schemas/RefinedSelectorsDocument"
                 url:
                   type: string
               required:
@@ -617,17 +594,9 @@ paths:
                         - metrics
                         type: object
                       sample_items:
-                        items:
-                          properties:
-                            image:
-                              nullable: true
-                              type: string
-                            title:
-                              type: string
-                          required:
-                          - title
-                          type: object
                         type: array
+                        items:
+                          "$ref": "#/components/schemas/PreviewSampleItem"
                       validation_issues:
                         items: {}
                         type: array
@@ -693,20 +662,7 @@ paths:
                       segment_strategy:
                         type: string
                       selectors:
-                        properties:
-                          items:
-                            properties:
-                              enhance:
-                                type: boolean
-                              selector:
-                                type: string
-                            required:
-                            - selector
-                            - enhance
-                            type: object
-                        required:
-                        - items
-                        type: object
+                        "$ref": "#/components/schemas/RefinedSelectorsDocument"
                     required:
                     - selectors
                     - segment_strategy
@@ -741,20 +697,7 @@ paths:
             schema:
               properties:
                 selectors:
-                  properties:
-                    items:
-                      properties:
-                        enhance:
-                          type: boolean
-                        selector:
-                          type: string
-                      required:
-                      - selector
-                      - enhance
-                      type: object
-                  required:
-                  - items
-                  type: object
+                  "$ref": "#/components/schemas/RefinedSelectorsDocument"
                 yaml:
                   type: string
               type: object
@@ -807,21 +750,9 @@ paths:
                         - issues
                         type: object
                       selectors:
+                        allOf:
+                        - "$ref": "#/components/schemas/RefinedSelectorsDocument"
                         nullable: true
-                        properties:
-                          items:
-                            properties:
-                              enhance:
-                                type: boolean
-                              selector:
-                                type: string
-                            required:
-                            - selector
-                            - enhance
-                            type: object
-                        required:
-                        - items
-                        type: object
                       yaml:
                         nullable: true
                         type: string
@@ -1270,6 +1201,79 @@ components:
       enum:
       - selectors
       type: string
+    RefinedSelectorsDocument:
+      description: Allowlisted selectors document for create, validate, and preview.
+      type: object
+      required:
+      - items
+      additionalProperties: false
+      properties:
+        items:
+          type: object
+          required:
+          - selector
+          additionalProperties: false
+          properties:
+            selector:
+              type: string
+            enhance:
+              type: boolean
+        title:
+          type: object
+          required:
+          - selector
+          - extractor
+          additionalProperties: false
+          properties:
+            selector:
+              type: string
+            extractor:
+              type: string
+              enum:
+              - text
+        url:
+          type: object
+          required:
+          - selector
+          - extractor
+          additionalProperties: false
+          properties:
+            selector:
+              type: string
+            extractor:
+              type: string
+              enum:
+              - href
+        published_at:
+          type: object
+          required:
+          - selector
+          - extractor
+          additionalProperties: false
+          properties:
+            selector:
+              type: string
+            extractor:
+              type: string
+              enum:
+              - text
+    PreviewSampleItem:
+      description: One preview meadow row returned by POST /feeds/preview.
+      type: object
+      required:
+      - title
+      properties:
+        title:
+          type: string
+        url:
+          type: string
+          nullable: true
+        published_at:
+          type: string
+          nullable: true
+        image:
+          type: string
+          nullable: true
 tags:
 - name: Root
   description: API metadata and service-level information.
diff --git a/spec/html2rss/web/api/v1_spec.rb b/spec/html2rss/web/api/v1_spec.rb
index 2eeb526e..0e90b4a9 100644
--- a/spec/html2rss/web/api/v1_spec.rb
+++ b/spec/html2rss/web/api/v1_spec.rb
@@ -737,11 +737,20 @@ def relative_feed_link_header(token)
     }
 
     it 'signs optional refined selectors into the feed token', :aggregate_failures do
-      post_feed_request(url: feed_url, selectors: { items: { selector: 'article', enhance: true } })
+      post_feed_request(
+        url: feed_url,
+        selectors: {
+          items: { selector: 'article', enhance: true },
+          title: { selector: 'h2', extractor: 'text' },
+          url: { selector: 'a', extractor: 'href' },
+          published_at: { selector: 'time', extractor: 'text' }
+        }
+      )
 
       token = expect_success_response(last_response).dig('data', 'feed', 'feed_token')
       decoded = Html2rss::Web::Auth.validate_and_decode_feed_token(token)
       expect(decoded.selectors.to_config_fragment.dig(:selectors, :items, :selector)).to eq('article')
+      expect(decoded.selectors.to_config_fragment.dig(:selectors, :title, :extractor)).to eq('text')
     end
 
     it 'creates a feed when request is valid', :aggregate_failures do
@@ -896,11 +905,20 @@ def post_validate(payload)
     }
 
     it 'returns a structured report for an allowlisted selectors object', :aggregate_failures do
-      post_validate(selectors: { items: { selector: 'article', enhance: true } })
+      post_validate(
+        selectors: {
+          items: { selector: 'article', enhance: true },
+          title: { selector: 'h2', extractor: 'text' },
+          url: { selector: 'a', extractor: 'href' },
+          published_at: { selector: 'time', extractor: 'text' }
+        }
+      )
 
       json = expect_success_response(last_response)
       expect(json.dig('data', 'report', 'success')).to be(true)
       expect(json.dig('data', 'selectors', 'items', 'selector')).to eq('article')
+      expect(json.dig('data', 'selectors', 'title', 'extractor')).to eq('text')
+      expect(json.dig('data', 'selectors', 'url', 'extractor')).to eq('href')
     end
 
     it 'returns a parse issue for unparseable yaml' do
@@ -926,7 +944,13 @@ def post_validate(payload)
   } do
     let(:preview_result) do
       Html2rss::Test::Result.new(
-        success: true, item_count: 2, sample_items: [{ 'title' => 'A' }], channel_title: 'Example',
+        success: true, item_count: 2,
+        sample_items: [{
+          'title' => 'A',
+          'url' => 'https://example.com/a',
+          'published_at' => '2026-01-02T03:04:05Z'
+        }],
+        channel_title: 'Example',
         channel_url: feed_url, strategy_used: :auto, duration_seconds: 0.1, validation_issues: [],
         error_message: nil, failure_kind: nil, rss: '<rss>do-not-leak</rss>'
       )
diff --git a/spec/support/openapi.rb b/spec/support/openapi.rb
index 4fdb125d..76c8859b 100644
--- a/spec/support/openapi.rb
+++ b/spec/support/openapi.rb
@@ -74,6 +74,124 @@ def publish_allowed_keys(spec)
       'enum' => Html2rss::Web::RefinedSelectors::ALLOWED_KEYS.map(&:to_s).sort,
       'type' => 'string'
     }
+    schemas['RefinedSelectorsDocument'] = refined_selectors_document
+    schemas['PreviewSampleItem'] = preview_sample_item
+    rewrite_studio_refs(spec)
+  end
+
+  # Closed selectors subtree the SPA may author. No post_process; enhance is
+  # omitted when false.
+  #
+  # @return [Hash]
+  def refined_selectors_document
+    {
+      'description' => 'Allowlisted selectors document for create, validate, and preview.',
+      'type' => 'object',
+      'required' => %w[items],
+      'additionalProperties' => false,
+      'properties' => {
+        'items' => {
+          'type' => 'object',
+          'required' => %w[selector],
+          'additionalProperties' => false,
+          'properties' => {
+            'selector' => { 'type' => 'string' },
+            'enhance' => { 'type' => 'boolean' }
+          }
+        },
+        'title' => refined_field(%w[text]),
+        'url' => refined_field(%w[href]),
+        'published_at' => refined_field(%w[text])
+      }
+    }
+  end
+
+  # @param extractors [Array<String>]
+  # @return [Hash]
+  def refined_field(extractors)
+    {
+      'type' => 'object',
+      'required' => %w[selector extractor],
+      'additionalProperties' => false,
+      'properties' => {
+        'selector' => { 'type' => 'string' },
+        'extractor' => { 'type' => 'string', 'enum' => extractors }
+      }
+    }
+  end
+
+  # @return [Hash]
+  def preview_sample_item
+    {
+      'description' => 'One preview meadow row returned by POST /feeds/preview.',
+      'type' => 'object',
+      'required' => %w[title],
+      'properties' => {
+        'title' => { 'type' => 'string' },
+        'url' => { 'type' => 'string', 'nullable' => true },
+        'published_at' => { 'type' => 'string', 'nullable' => true },
+        'image' => { 'type' => 'string', 'nullable' => true }
+      }
+    }
+  end
+
+  # Replace example-inferred items-only hulls with the stamped closed schemas.
+  #
+  # @param spec [Hash]
+  # @return [void]
+  def rewrite_studio_refs(spec)
+    walk(spec) do |node|
+      properties = node['properties']
+      next unless properties.is_a?(Hash)
+
+      rewrite_selectors_property(properties)
+      rewrite_sample_items_property(properties)
+    end
+  end
+
+  # @param properties [Hash]
+  # @return [void]
+  def rewrite_selectors_property(properties)
+    schema = properties['selectors']
+    return unless selectors_document_hull?(schema)
+
+    properties['selectors'] = if schema['nullable']
+                                {
+                                  'allOf' => [{ '$ref' => '#/components/schemas/RefinedSelectorsDocument' }],
+                                  'nullable' => true
+                                }
+                              else
+                                { '$ref' => '#/components/schemas/RefinedSelectorsDocument' }
+                              end
+  end
+
+  # @param properties [Hash]
+  # @return [void]
+  def rewrite_sample_items_property(properties)
+    schema = properties['sample_items']
+    return unless sample_items_hull?(schema)
+
+    properties['sample_items'] = {
+      'type' => 'array',
+      'items' => { '$ref' => '#/components/schemas/PreviewSampleItem' }
+    }
+  end
+
+  # @param schema [Object]
+  # @return [Boolean]
+  def selectors_document_hull?(schema)
+    return false unless schema.is_a?(Hash)
+
+    items = schema.dig('properties', 'items')
+    items.is_a?(Hash) && items.dig('properties', 'selector').is_a?(Hash)
+  end
+
+  # @param schema [Object]
+  # @return [Boolean]
+  def sample_items_hull?(schema)
+    return false unless schema.is_a?(Hash) && schema['type'] == 'array'
+
+    schema.dig('items', 'properties', 'title').is_a?(Hash)
   end
 
   # rspec-openapi seeds `components` symbol-keyed (`securitySchemes`), so a
diff --git a/spec/support/openapi_runtime_contract_spec.rb b/spec/support/openapi_runtime_contract_spec.rb
new file mode 100644
index 00000000..9fd4c2ce
--- /dev/null
+++ b/spec/support/openapi_runtime_contract_spec.rb
@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe OpenapiRuntimeContract do
+  it 'publishes the closed refined selectors document and preview sample item', :aggregate_failures do
+    spec = {
+      'components' => { 'schemas' => {} },
+      'paths' => {
+        '/feeds/preview' => {
+          'post' => {
+            'requestBody' => {
+              'content' => {
+                'application/json' => {
+                  'schema' => {
+                    'type' => 'object',
+                    'properties' => {
+                      'selectors' => {
+                        'type' => 'object',
+                        'properties' => {
+                          'items' => {
+                            'type' => 'object',
+                            'properties' => { 'selector' => { 'type' => 'string' } }
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            },
+            'responses' => {
+              '200' => {
+                'content' => {
+                  'application/json' => {
+                    'schema' => {
+                      'type' => 'object',
+                      'properties' => {
+                        'data' => {
+                          'type' => 'object',
+                          'properties' => {
+                            'sample_items' => {
+                              'type' => 'array',
+                              'items' => {
+                                'type' => 'object',
+                                'properties' => { 'title' => { 'type' => 'string' } }
+                              }
+                            },
+                            'selectors' => {
+                              'nullable' => true,
+                              'type' => 'object',
+                              'properties' => {
+                                'items' => {
+                                  'type' => 'object',
+                                  'properties' => { 'selector' => { 'type' => 'string' } }
+                                }
+                              }
+                            }
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+
+    described_class.stamp(spec)
+
+    document = spec.dig('components', 'schemas', 'RefinedSelectorsDocument')
+    expect(document.dig('properties', 'title', 'properties', 'extractor', 'enum')).to eq(%w[text])
+    expect(document.dig('properties', 'url', 'properties', 'extractor', 'enum')).to eq(%w[href])
+    expect(document.dig('properties', 'items', 'required')).to eq(%w[selector])
+    expect(document['additionalProperties']).to be(false)
+
+    sample = spec.dig('components', 'schemas', 'PreviewSampleItem')
+    expect(sample['properties'].keys).to include('title', 'url', 'published_at', 'image')
+
+    request_selectors = spec.dig(
+      'paths', '/feeds/preview', 'post', 'requestBody', 'content', 'application/json',
+      'schema', 'properties', 'selectors'
+    )
+    expect(request_selectors).to eq('$ref' => '#/components/schemas/RefinedSelectorsDocument')
+
+    sample_items = spec.dig(
+      'paths', '/feeds/preview', 'post', 'responses', '200', 'content', 'application/json',
+      'schema', 'properties', 'data', 'properties', 'sample_items'
+    )
+    expect(sample_items).to eq(
+      'type' => 'array',
+      'items' => { '$ref' => '#/components/schemas/PreviewSampleItem' }
+    )
+
+    echo = spec.dig(
+      'paths', '/feeds/preview', 'post', 'responses', '200', 'content', 'application/json',
+      'schema', 'properties', 'data', 'properties', 'selectors'
+    )
+    expect(echo).to eq(
+      'allOf' => [{ '$ref' => '#/components/schemas/RefinedSelectorsDocument' }],
+      'nullable' => true
+    )
+  end
+end

From c5c1aa97cd30225b01a84c4a8007aac4c4e0f1dd Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 20 Sep 2026 11:47:51 +0200
Subject: [PATCH 044/108] refactor(studio): type-bound draft without fixup or
 preserve bags

---
 frontend/src/__tests__/ConfigStudio.test.tsx |   3 +-
 frontend/src/__tests__/apiHttp.feeds.test.ts |   7 +-
 frontend/src/__tests__/useStudio.test.ts     |  57 +++--
 frontend/src/components/ConfigStudio.tsx     |   3 +-
 frontend/src/feed/useFeedCreation.ts         |   3 +-
 frontend/src/feed/useFeedFlow.ts             |   3 +-
 frontend/src/feeds/feedsService.ts           |   3 +-
 frontend/src/studio/selectorDraft.ts         | 245 ++++---------------
 frontend/src/studio/studioService.ts         |   9 +-
 frontend/src/studio/useStudio.ts             |  12 +-
 10 files changed, 101 insertions(+), 244 deletions(-)

diff --git a/frontend/src/__tests__/ConfigStudio.test.tsx b/frontend/src/__tests__/ConfigStudio.test.tsx
index 05fb3009..2c6108b0 100644
--- a/frontend/src/__tests__/ConfigStudio.test.tsx
+++ b/frontend/src/__tests__/ConfigStudio.test.tsx
@@ -1,6 +1,7 @@
 import { describe, it, expect, vi } from 'vitest';
 import { render, screen, fireEvent, waitFor, act } from '@testing-library/preact';
 import { http, HttpResponse } from 'msw';
+import type { RefinedSelectorsDocument } from '../api/generated/types.gen';
 import { server } from './mocks/server';
 import { ConfigStudio, STUDIO_URL_SETTLE_MS } from '../components/ConfigStudio';
 import { COPY } from '../journey/copy';
@@ -8,7 +9,7 @@ import { COPY } from '../journey/copy';
 const pageUrl = 'https://example.com/articles';
 
 function renderStudio(
-  onGenerate = vi.fn<(selectors: Record<string, unknown>) => Promise<void>>(),
+  onGenerate = vi.fn<(selectors: RefinedSelectorsDocument) => Promise<void>>(),
   {
     url = pageUrl,
     onUrlChange = vi.fn(),
diff --git a/frontend/src/__tests__/apiHttp.feeds.test.ts b/frontend/src/__tests__/apiHttp.feeds.test.ts
index 28b72677..35ddb43f 100644
--- a/frontend/src/__tests__/apiHttp.feeds.test.ts
+++ b/frontend/src/__tests__/apiHttp.feeds.test.ts
@@ -44,7 +44,10 @@ describe('postCreateFeed', () => {
     const fetchMock = vi
       .spyOn(globalThis, 'fetch')
       .mockResolvedValue(Response.json(createdFeed, { status: 201 }));
-    const selectors = { items: { selector: 'article', enhance: false }, title: { selector: 'h2' } };
+    const selectors = {
+      items: { selector: 'article' },
+      title: { selector: 'h2', extractor: 'text' as const },
+    };
 
     const envelope = await postCreateFeed('https://example.com/articles', 'token-123', selectors);
     const input = fetchMock.mock.calls[0]?.[0];
@@ -68,7 +71,7 @@ describe('studio JSON writes', () => {
 
   it('POSTs validate, preview, and suggest through the generated client', async () => {
     const fetchMock = vi.spyOn(globalThis, 'fetch').mockResolvedValue(Response.json({ success: true }));
-    const selectors = { items: { selector: 'article', enhance: false } };
+    const selectors = { items: { selector: 'article' } };
 
     await postValidateFeed('token-123', selectors);
     await postPreviewFeed('token-123', 'https://example.com', selectors);
diff --git a/frontend/src/__tests__/useStudio.test.ts b/frontend/src/__tests__/useStudio.test.ts
index b2f1f395..a633370e 100644
--- a/frontend/src/__tests__/useStudio.test.ts
+++ b/frontend/src/__tests__/useStudio.test.ts
@@ -4,7 +4,6 @@ import {
   draftFromSelectors,
   emptyDraft,
   selectorsFromDraft,
-  withFieldFixup,
   withFieldSelector,
 } from '../studio/selectorDraft';
 import { STUDIO_PREVIEW_SETTLE_MS, STUDIO_VALIDATE_DELAY_MS, useStudio } from '../studio/useStudio';
@@ -67,47 +66,47 @@ describe('selector draft', () => {
     expect(emptyDraft().itemsSelector).toBe('a[href]');
   });
 
-  it('round-trips field fixups and untouched keys', () => {
+  it('round-trips closed field selectors without fixup or preserve bags', () => {
     const drafted = draftFromSelectors({
       items: { selector: 'article', enhance: true, order: 'reverse' },
       guid: ['title'],
+      title: { selector: 'h2', extractor: 'text' },
     });
     expect(drafted).toBeDefined();
     if (!drafted) return;
 
-    const withTitle = withFieldFixup(withFieldSelector(drafted, 'title', 'h2'), 'title', {
-      kind: 'strip_html',
-    });
-    const withLink = withFieldSelector(withTitle, 'link', 'a');
-    const withDate = withFieldFixup(withFieldSelector(withLink, 'published', 'time'), 'published', {
-      kind: 'trim_length',
-      length: '12',
-    });
-    const withAffix = withFieldFixup(withDate, 'title', { kind: 'remove_affix', text: 'a.b' });
+    expect(drafted.itemsSelector).toBe('article');
+    expect(drafted.enhance).toBe(true);
+    expect(drafted.fields.title.selector).toBe('h2');
 
-    expect(withAffix.itemsPreserved).toEqual({ order: 'reverse' });
-    const wire = selectorsFromDraft(withAffix);
+    const withLink = withFieldSelector(drafted, 'link', 'a');
+    const withDate = withFieldSelector(withLink, 'published', 'time');
+    const wire = selectorsFromDraft(withDate);
     expect(wire).toEqual({
-      items: { selector: 'article', enhance: true, order: 'reverse' },
-      title: {
-        selector: 'h2',
-        extractor: 'text',
-        post_process: [{ name: 'gsub', pattern: String.raw`^(?:a\.b)|(?:a\.b)$`, replacement: '' }],
-      },
+      items: { selector: 'article', enhance: true },
+      title: { selector: 'h2', extractor: 'text' },
       url: { selector: 'a', extractor: 'href' },
-      published_at: {
-        selector: 'time',
-        extractor: 'text',
-        post_process: [{ name: 'substring', start: 0, end: 11 }],
-      },
-      guid: ['title'],
+      published_at: { selector: 'time', extractor: 'text' },
     });
 
     const again = draftFromSelectors(wire);
-    expect(again?.fields.title.fixup).toEqual({ kind: 'remove_affix', text: 'a.b' });
-    expect(again?.fields.published.fixup).toEqual({ kind: 'trim_length', length: '12' });
-    expect(again?.fields.link).toEqual({ selector: 'a', fixup: { kind: 'none' } });
-    expect(selectorsFromDraft(again ?? withAffix)).toEqual(wire);
+    expect(again?.fields.title.selector).toBe('h2');
+    expect(again?.fields.link.selector).toBe('a');
+    expect(again?.fields.published.selector).toBe('time');
+    expect(selectorsFromDraft(again ?? withDate)).toEqual(wire);
+  });
+
+  it('rejects field documents that still carry post_process', () => {
+    expect(
+      draftFromSelectors({
+        items: { selector: 'article' },
+        title: {
+          selector: 'h2',
+          extractor: 'text',
+          post_process: [{ name: 'gsub', pattern: 'x', replacement: '' }],
+        },
+      })
+    ).toBeUndefined();
   });
 });
 
diff --git a/frontend/src/components/ConfigStudio.tsx b/frontend/src/components/ConfigStudio.tsx
index bbca2e74..e53509f9 100644
--- a/frontend/src/components/ConfigStudio.tsx
+++ b/frontend/src/components/ConfigStudio.tsx
@@ -1,5 +1,6 @@
 import type { JSX } from 'preact';
 import { useEffect, useRef, useState } from 'preact/hooks';
+import type { RefinedSelectorsDocument } from '../api/generated/types.gen';
 import { COPY } from '../journey/copy';
 import { PreviewItem } from './PreviewItem';
 import { Notice } from './Notice';
@@ -15,7 +16,7 @@ interface ConfigStudioProperties {
   readonly token: string;
   readonly onUrlChange: (url: string) => void;
   readonly onUrlCleared: () => void;
-  readonly onGenerate: (selectors: Record<string, unknown>) => Promise<void>;
+  readonly onGenerate: (selectors: RefinedSelectorsDocument) => Promise<void>;
 }
 
 interface OpenPanel {
diff --git a/frontend/src/feed/useFeedCreation.ts b/frontend/src/feed/useFeedCreation.ts
index f8a38ab0..7c4ef28d 100644
--- a/frontend/src/feed/useFeedCreation.ts
+++ b/frontend/src/feed/useFeedCreation.ts
@@ -1,5 +1,6 @@
 import { useEffect, useRef, useState } from 'preact/hooks';
 import type { CreatedFeedResult, FeedCreationError } from '../api/contracts';
+import type { RefinedSelectorsDocument } from '../api/generated/types.gen';
 import {
   normalizeFeedCreationError,
   requestFeedCreation,
@@ -39,7 +40,7 @@ export function useFeedCreation() {
     []
   );
 
-  async function createFeed(normalizedUrl: string, token: string, selectors?: Record<string, unknown>) {
+  async function createFeed(normalizedUrl: string, token: string, selectors?: RefinedSelectorsDocument) {
     const requestId = requestIdReference.current + 1;
     requestIdReference.current = requestId;
     cancelPreview();
diff --git a/frontend/src/feed/useFeedFlow.ts b/frontend/src/feed/useFeedFlow.ts
index cfb107cc..3857d2e4 100644
--- a/frontend/src/feed/useFeedFlow.ts
+++ b/frontend/src/feed/useFeedFlow.ts
@@ -4,6 +4,7 @@ import { decideJourney } from './decideJourney';
 import { clearFeedDraftState, loadFeedDraftState, saveFeedDraftState } from '../utils/feedWorkflowStorage';
 import { expandCreateUrl } from '../utils/url';
 import type { FeedCreationError } from '../api/contracts';
+import type { RefinedSelectorsDocument } from '../api/generated/types.gen';
 import { isFeedCreationError } from '../feeds/feedsService';
 import { COPY } from '../journey/copy';
 import type { AppRoute } from '../routes/appRoute';
@@ -249,7 +250,7 @@ export function useFeedFlow({
 
   const sourceUrl = inMemorySourceUrl(feedFormData.url, result?.feed.url);
 
-  const generateFromStudio = async (selectors: Record<string, unknown>) => {
+  const generateFromStudio = async (selectors: RefinedSelectorsDocument) => {
     const expanded = expandCreateUrl(sourceUrl);
     if ('error' in expanded) {
       throw new Error(expanded.error === 'empty' ? COPY.urlRequired : COPY.invalidUrlFormat);
diff --git a/frontend/src/feeds/feedsService.ts b/frontend/src/feeds/feedsService.ts
index f092b2a6..52cf3951 100644
--- a/frontend/src/feeds/feedsService.ts
+++ b/frontend/src/feeds/feedsService.ts
@@ -1,4 +1,5 @@
 import type { FeedRecord } from '../api/contracts';
+import type { RefinedSelectorsDocument } from '../api/generated/types.gen';
 import { postCreateFeed } from '../api/http/feeds';
 import { COPY } from '../journey/copy';
 import {
@@ -42,7 +43,7 @@ function rawFeedRecord(body: unknown): RawFeedRecord | undefined {
 export async function requestFeedCreation(
   url: string,
   token: string,
-  selectors?: Record<string, unknown>
+  selectors?: RefinedSelectorsDocument
 ): Promise<FeedRecord> {
   const envelope = await postCreateFeed(url, token, selectors);
   const payload = feedApiResponse(envelope.body);
diff --git a/frontend/src/studio/selectorDraft.ts b/frontend/src/studio/selectorDraft.ts
index 9cbf01ec..e1b462e9 100644
--- a/frontend/src/studio/selectorDraft.ts
+++ b/frontend/src/studio/selectorDraft.ts
@@ -1,45 +1,31 @@
 /**
  * Closed refine draft for the allowlisted selectors document.
  *
- * The screen edits an items selector, enhance, and three fields. Optional
- * fixups become gem post-processors here; that vocabulary does not leave
- * this module. Unknown selector keys stay in `preserved` so a validate echo
- * does not drop them.
+ * The screen edits an items selector, enhance, and three fields. Wire mapping
+ * lives here; HTTP adapters only see {@link RefinedSelectorsDocument}.
  */
 
+import type { RefinedSelectorsDocument } from '../api/generated/types.gen';
+
 export const STUDIO_FIELDS = ['title', 'link', 'published'] as const;
 export type StudioFieldId = (typeof STUDIO_FIELDS)[number];
 
-export type FieldFixup =
-  | { readonly kind: 'none' }
-  | { readonly kind: 'strip_html' }
-  | { readonly kind: 'trim_length'; readonly length: string }
-  | { readonly kind: 'remove_affix'; readonly text: string };
-
 export interface FieldDraft {
   readonly selector: string;
-  readonly fixup: FieldFixup;
 }
 
 export interface StudioDraft {
   readonly itemsSelector: string;
   readonly enhance: boolean;
   readonly fields: Readonly<Record<StudioFieldId, FieldDraft>>;
-  readonly preserved: Readonly<Record<string, unknown>>;
-  readonly itemsPreserved: Readonly<Record<string, unknown>>;
 }
 
 export type IssuePlace =
   | { readonly kind: 'items' }
   | { readonly kind: 'enhance' }
-  | { readonly kind: 'field'; readonly field: StudioFieldId; readonly control: 'selector' | 'fixup' }
+  | { readonly kind: 'field'; readonly field: StudioFieldId; readonly control: 'selector' }
   | { readonly kind: 'hidden' };
 
-const STRIP_HTML_PATTERN = '<[^>]*>';
-const AFFIX_PREFIX = '^(?:';
-const AFFIX_MARKER = ')|(?:';
-const AFFIX_SUFFIX = ')$';
-
 /** Wire spelling of Html2rss::Selectors::DEFAULT_ITEMS_SELECTOR. */
 export const DEFAULT_ITEMS_SELECTOR = 'a[href]';
 
@@ -58,21 +44,33 @@ export function emptyDraft(): StudioDraft {
       link: blankField(),
       published: blankField(),
     },
-    preserved: {},
-    itemsPreserved: {},
   };
 }
 
-export function selectorsFromDraft(draft: StudioDraft): Record<string, unknown> {
-  const selectors = withoutKeys(draft.preserved, ['items', 'title', 'url', 'published_at']);
-  const items: Record<string, unknown> = { ...draft.itemsPreserved };
-  if (draft.enhance) items.enhance = true;
-  if (draft.itemsSelector.length > 0) items.selector = draft.itemsSelector;
-  selectors.items = items;
+export function selectorsFromDraft(draft: StudioDraft): RefinedSelectorsDocument {
+  const selectors: RefinedSelectorsDocument = {
+    items: draft.enhance
+      ? { selector: draft.itemsSelector, enhance: true }
+      : { selector: draft.itemsSelector },
+  };
 
   for (const field of STUDIO_FIELDS) {
     const wire = fieldToWire(draft.fields[field], field);
-    if (wire) selectors[wireKey(field)] = wire;
+    if (!wire) continue;
+    switch (field) {
+      case 'title': {
+        selectors.title = wire;
+        break;
+      }
+      case 'link': {
+        selectors.url = wire;
+        break;
+      }
+      case 'published': {
+        selectors.published_at = wire;
+        break;
+      }
+    }
   }
 
   return selectors;
@@ -83,24 +81,17 @@ export function draftFromSelectors(value: unknown): StudioDraft | undefined {
 
   const items = isPlainRecord(value.items) ? value.items : undefined;
   const fields = emptyFields();
-  const preserved: Record<string, unknown> = {};
-
-  for (const [key, nested] of Object.entries(value)) {
-    if (key === 'items') continue;
-    const parsed = parseField(key, nested);
-    if (parsed) {
-      fields[parsed.field] = parsed.draft;
-    } else {
-      preserved[key] = nested;
-    }
+  for (const key of ['title', 'url', 'published_at'] as const) {
+    if (!(key in value)) continue;
+    const parsed = parseField(key, value[key]);
+    if (!parsed) return;
+    fields[parsed.field] = parsed.draft;
   }
 
   return {
     itemsSelector: typeof items?.selector === 'string' ? items.selector : '',
     enhance: items?.enhance === true,
     fields,
-    preserved,
-    itemsPreserved: items ? withoutKeys(items, ['selector', 'enhance']) : {},
   };
 }
 
@@ -113,11 +104,7 @@ export function withEnhance(draft: StudioDraft, isEnhanced: boolean): StudioDraf
 }
 
 export function withFieldSelector(draft: StudioDraft, field: StudioFieldId, selector: string): StudioDraft {
-  return mapField(draft, field, (current) => ({ ...current, selector }));
-}
-
-export function withFieldFixup(draft: StudioDraft, field: StudioFieldId, fixup: FieldFixup): StudioDraft {
-  return mapField(draft, field, (current) => ({ ...current, fixup }));
+  return mapField(draft, field, () => ({ selector }));
 }
 
 export function applyItemsSuggestion(
@@ -137,16 +124,7 @@ export function issuePlace(path: readonly string[]): IssuePlace {
 
   const field = typeof head === 'string' ? fieldFromWireKey(head) : undefined;
   if (!field) return { kind: 'hidden' };
-  return {
-    kind: 'field',
-    field,
-    control: scope.includes('post_process') ? 'fixup' : 'selector',
-  };
-}
-
-export function hasIncompleteTrim(fixup: FieldFixup): boolean {
-  if (fixup.kind !== 'trim_length' || fixup.length.trim().length === 0) return false;
-  return trimEnd(fixup.length) === undefined;
+  return { kind: 'field', field, control: 'selector' };
 }
 
 function emptyFields(): Record<StudioFieldId, FieldDraft> {
@@ -158,7 +136,7 @@ function emptyFields(): Record<StudioFieldId, FieldDraft> {
 }
 
 function blankField(): FieldDraft {
-  return { selector: '', fixup: { kind: 'none' } };
+  return { selector: '' };
 }
 
 function mapField(
@@ -175,114 +153,37 @@ function mapField(
   };
 }
 
-function fieldToWire(field: FieldDraft, id: StudioFieldId): Record<string, unknown> | undefined {
+function fieldToWire(
+  field: FieldDraft,
+  id: StudioFieldId
+): RefinedSelectorsDocument['title'] | RefinedSelectorsDocument['url'] | undefined {
   if (field.selector.length === 0) return;
-  const wire: Record<string, unknown> = {
-    selector: field.selector,
-    extractor: extractorFor(id),
-  };
-  const processor = fixupToWire(field.fixup);
-  if (processor) wire.post_process = [processor];
-  return wire;
-}
-
-function fixupToWire(fixup: FieldFixup): Record<string, unknown> | undefined {
-  switch (fixup.kind) {
-    case 'none': {
-      return;
-    }
-    case 'strip_html': {
-      return { name: 'gsub', pattern: STRIP_HTML_PATTERN, replacement: '' };
-    }
-    case 'trim_length': {
-      const end = trimEnd(fixup.length);
-      if (end === undefined) return;
-      return { name: 'substring', start: 0, end };
+  switch (id) {
+    case 'link': {
+      return { selector: field.selector, extractor: 'href' };
     }
-    case 'remove_affix': {
-      if (fixup.text.length === 0) return;
-      return { name: 'gsub', pattern: affixPattern(fixup.text), replacement: '' };
+    case 'title':
+    case 'published': {
+      return { selector: field.selector, extractor: 'text' };
     }
   }
 }
 
 function parseField(
-  key: string,
+  key: 'title' | 'url' | 'published_at',
   value: unknown
 ): { readonly field: StudioFieldId; readonly draft: FieldDraft } | undefined {
   const field = fieldFromWireKey(key);
-  if (!field || !isPlainRecord(value) || hasForeignKeys(value)) return;
-
-  const extractor = value.extractor;
-  if (extractor !== undefined && extractor !== extractorFor(field)) return;
-
-  const fixup = parseFixup(value.post_process);
-  if (!fixup) return;
-
-  return {
-    field,
-    draft: {
-      selector: typeof value.selector === 'string' ? value.selector : '',
-      fixup,
-    },
-  };
-}
+  if (!field || !isPlainRecord(value)) return;
+  if (typeof value.selector !== 'string') return;
 
-function hasForeignKeys(value: Readonly<Record<string, unknown>>): boolean {
-  for (const key of Object.keys(value)) {
-    if (key !== 'selector' && key !== 'extractor' && key !== 'post_process') return true;
+  const expected = extractorFor(field);
+  if (value.extractor !== undefined && value.extractor !== expected) return;
+  for (const nested of Object.keys(value)) {
+    if (nested !== 'selector' && nested !== 'extractor') return;
   }
-  return false;
-}
 
-function parseFixup(value: unknown): FieldFixup | undefined {
-  if (value === undefined) return { kind: 'none' };
-  if (!Array.isArray(value) || value.length !== 1) return;
-  return parseProcessor(value[0]);
-}
-
-function parseProcessor(value: unknown): FieldFixup | undefined {
-  if (!isPlainRecord(value) || typeof value.name !== 'string') return;
-
-  switch (value.name) {
-    case 'gsub': {
-      if (typeof value.pattern !== 'string' || typeof value.replacement !== 'string') return;
-      return parseGsub(value.pattern, value.replacement);
-    }
-    case 'substring': {
-      return parseTrim(value.start, value.end);
-    }
-    default: {
-      return;
-    }
-  }
-}
-
-function parseGsub(pattern: string, replacement: string): FieldFixup | undefined {
-  if (replacement !== '') return;
-  if (pattern === STRIP_HTML_PATTERN) return { kind: 'strip_html' };
-  const text = affixText(pattern);
-  if (text === undefined || affixPattern(text) !== pattern) return;
-  return { kind: 'remove_affix', text };
-}
-
-function parseTrim(start: unknown, end: unknown): FieldFixup | undefined {
-  if (start !== 0 || typeof end !== 'number' || !Number.isSafeInteger(end) || end < 1) return;
-  return { kind: 'trim_length', length: String(end + 1) };
-}
-
-function wireKey(field: StudioFieldId): 'title' | 'url' | 'published_at' {
-  switch (field) {
-    case 'title': {
-      return 'title';
-    }
-    case 'link': {
-      return 'url';
-    }
-    case 'published': {
-      return 'published_at';
-    }
-  }
+  return { field, draft: { selector: value.selector } };
 }
 
 function fieldFromWireKey(key: string): StudioFieldId | undefined {
@@ -318,45 +219,3 @@ function selectorScope(path: readonly string[]): readonly string[] {
   const index = path.indexOf('selectors');
   return index === -1 ? path : path.slice(index + 1);
 }
-
-function trimEnd(length: string): number | undefined {
-  if (!/^\d+$/.test(length)) return;
-  const parsed = Number(length);
-  if (!Number.isSafeInteger(parsed) || parsed < 2) return;
-  return parsed - 1;
-}
-
-function affixPattern(text: string): string {
-  const escaped = escapeRegexp(text);
-  return `${AFFIX_PREFIX}${escaped}${AFFIX_MARKER}${escaped}${AFFIX_SUFFIX}`;
-}
-
-function affixText(pattern: string): string | undefined {
-  if (!pattern.startsWith(AFFIX_PREFIX) || !pattern.endsWith(AFFIX_SUFFIX)) return;
-  const body = pattern.slice(AFFIX_PREFIX.length, pattern.length - AFFIX_SUFFIX.length);
-  const splitAt = body.indexOf(AFFIX_MARKER);
-  if (splitAt <= 0) return;
-  const left = body.slice(0, splitAt);
-  const right = body.slice(splitAt + AFFIX_MARKER.length);
-  if (left !== right) return;
-  return unescapeRegexp(left);
-}
-
-function escapeRegexp(value: string): string {
-  return value.replaceAll(/[\\^$.*+?()[\]{}|]/g, (character) => `\\${character}`);
-}
-
-function unescapeRegexp(value: string): string {
-  return value.replaceAll(/\\(.)/g, (match) => match.slice(1));
-}
-
-function withoutKeys(
-  value: Readonly<Record<string, unknown>>,
-  keys: readonly string[]
-): Record<string, unknown> {
-  const next: Record<string, unknown> = {};
-  for (const [key, nested] of Object.entries(value)) {
-    if (!keys.includes(key)) next[key] = nested;
-  }
-  return next;
-}
diff --git a/frontend/src/studio/studioService.ts b/frontend/src/studio/studioService.ts
index 7a296b4f..848f3834 100644
--- a/frontend/src/studio/studioService.ts
+++ b/frontend/src/studio/studioService.ts
@@ -1,11 +1,10 @@
 /**
  * Studio transport. The only place the `{ success, data }` envelope is unwrapped.
  *
- * Issue codes are the generated client's closed union. Selector documents are
- * parsed into {@link StudioDraft} because the published selectors schema is the
- * example shape (`items` only), not the allowlisted subtree.
+ * Issue codes are the generated client's closed union. Selector documents map
+ * through {@link StudioDraft} at this boundary.
  */
-import type { ValidateFeedConfigResponses } from '../api/generated';
+import type { RefinedSelectorsDocument, ValidateFeedConfigResponses } from '../api/generated';
 import type { HttpEnvelope } from '../api/http/client';
 import { postPreviewFeed, postSuggestSelectors, postValidateFeed } from '../api/http/feeds';
 import { isAbortError } from '../feeds/feedsService';
@@ -99,7 +98,7 @@ export async function suggestStudioSelectors(
 
 async function validateStudio(
   token: string,
-  selectors: Record<string, unknown>,
+  selectors: RefinedSelectorsDocument,
   signal?: AbortSignal
 ): Promise<StudioValidationOutcome> {
   return parseValidation(await studioData(await postValidateFeed(token, selectors, signal)));
diff --git a/frontend/src/studio/useStudio.ts b/frontend/src/studio/useStudio.ts
index c51378dd..ee01603b 100644
--- a/frontend/src/studio/useStudio.ts
+++ b/frontend/src/studio/useStudio.ts
@@ -11,15 +11,14 @@ import {
   type StudioSuggestion,
   type StudioValidationOutcome,
 } from './studioService';
+import type { RefinedSelectorsDocument } from '../api/generated/types.gen';
 import {
   applyItemsSuggestion,
   emptyDraft,
   selectorsFromDraft,
   withEnhance,
-  withFieldFixup,
   withFieldSelector,
   withItemsSelector,
-  type FieldFixup,
   type StudioDraft,
   type StudioFieldId,
 } from './selectorDraft';
@@ -239,10 +238,6 @@ export function useStudio({
     editSelectors((draft) => withFieldSelector(draft, field, selector));
   };
 
-  const setFieldFixup = (field: StudioFieldId, fixup: FieldFixup) => {
-    editSelectors((draft) => withFieldFixup(draft, field, fixup));
-  };
-
   async function requestSuggestion() {
     const requestId = ++suggestRequestReference.current;
     try {
@@ -277,7 +272,7 @@ export function useStudio({
     void runPreview(requestId);
   }
 
-  async function save(create: (selectors: Record<string, unknown>) => Promise<void>) {
+  async function save(create: (selectors: RefinedSelectorsDocument) => Promise<void>) {
     const requestId = ++saveRequestReference.current;
     const current = stateReference.current;
     setState({ phase: 'saving', draft: current.draft, yaml: current.yaml, live: current.live });
@@ -301,7 +296,6 @@ export function useStudio({
     setItemsSelector,
     setEnhance,
     setFieldSelector,
-    setFieldFixup,
     requestSuggestion: () => {
       void requestSuggestion();
     },
@@ -336,8 +330,6 @@ function adoptServerDraft(sent: StudioDraft, incoming: StudioDraft): StudioDraft
     ...sent,
     itemsSelector: incoming.itemsSelector,
     enhance: incoming.enhance,
-    preserved: incoming.preserved,
-    itemsPreserved: incoming.itemsPreserved,
   };
 }
 

From d250e5d06115ad68542492d40a45d7992591bcb2 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 20 Sep 2026 11:49:37 +0200
Subject: [PATCH 045/108] feat(studio): lead refine with preview meadow and
 compact controls

---
 docs/design-system.md                        |   2 +-
 frontend/src/__tests__/ConfigStudio.test.tsx |  14 +
 frontend/src/components/ConfigStudio.tsx     | 256 ++++++++++---------
 frontend/src/styles/main.css                 |  30 ++-
 4 files changed, 174 insertions(+), 128 deletions(-)

diff --git a/docs/design-system.md b/docs/design-system.md
index 272d3b3c..41397b80 100644
--- a/docs/design-system.md
+++ b/docs/design-system.md
@@ -42,7 +42,7 @@ If a page looks like it came from a different product, the change is wrong even
 - **Token gate:** a native `<dialog>` over the still-mounted, inert URL task (one interactive task). Auth copy is in-field (`tokenError`); ActionFeedback stays on create. Access Token persists until Logout with no storage UI.
 - **Result:** primary CTA is **Copy feed URL**. Open feed / JSON / feed-reader are demoted secondary actions and stay available while preview loads. Preview is non-blocking confirmation only. **Refine selectors** is one quiet action beside create another.
 - **Empty extraction:** **Refine selectors** is one quiet action beside Try again when the extraction is empty. It is not offered for other create errors.
-- **Refine:** `#/refine` is memory-bound Sam recovery (see [personas.md](personas.md) J2/J3/J3b). No token in the route. Same frame as Create/Result: one `layout-rail-reading` / `layout-stack` rail — never a two-column paddock. An editable **URL** field (same vocabulary as Create, `input--mono`, no trailing CTA) sits under the title; changing it re-suggests and re-previews without leaving refine or running catalog find. Empty URL recovers onto remounted `#/create`. The items selector is the task; an empty selector is filled once from suggestion, and Enhance follows that suggestion until the user changes either. Controls use one grammar: eyebrow above the control, stacked with token gaps. **Apply suggestion** is `btn--quiet` on the items field. Enhance is one row (eyebrow + checkbox). **Save and generate feed** is the only `btn--primary`, in `ui-actions` like Result. A live preview meadow (`.ui-item-list`) grows below quiet Title/Link/Published meta after validation; an authenticated session may show a sample image when the preview item includes an image URL. Fix a field opens one selector panel **in the stack** for Title, Link, or Published date (no strip/trim/affix cleanup). View as YAML is read-only, demoted, and captioned as a selectors fragment — not a feeds.yml. Native-feed and save-failure Notices sit on the same rail (wire `Decision#message` for save failures — never create-journey copy). When studio is disabled on the instance, Refine actions stay hidden and `#/refine` bounces to create. Focus is the items selector.
+- **Refine:** `#/refine` is memory-bound Sam recovery (see [personas.md](personas.md) J2/J3/J3b). No token in the route. Same frame as Result: a `result-shell` / `layout-stack` rail — never a mega-card bisected by the fixed footer, never a two-column paddock. First viewport leads with the live preview meadow (`.ui-item-list`) after validation, then compact controls: items selector, left-aligned **Apply suggestion**, a large Enhance hit target, and **Save and generate feed** as the only `btn--primary` in `ui-actions`. URL, native-feed Notice, and View as YAML are demoted support below the controls. Changing the URL re-suggests and re-previews without leaving refine or running catalog find; empty URL recovers onto remounted `#/create`. Prefill: an empty items selector is filled once from suggestion, and Enhance follows that suggestion until the user changes either. Wire is the typed closed selectors document (no strip/trim/affix cleanup UI). Fix a field opens one selector panel **in the stack** for Title, Link, or Published date. View as YAML is read-only and captioned as a selectors fragment — not a feeds.yml. Save-failure Notices use wire `Decision#message` — never create-journey copy. When studio is disabled on the instance, Refine actions stay hidden and `#/refine` bounces to create. Focus is the items selector.
 - **Unmatched result:** `#/result/:token` is valid only with a matching in-memory result. Missing or mismatched tokens recover onto remounted `#/create` (no API rehydrate, no failure chrome, no durable shareable result page).
 - **Status eyebrow:** one vocabulary (`Feed ready`) on the result header; preview progress lives in the preview section.
 - **Focus:** create autofocuses the URL field; token autofocuses the token field; result focuses the Copy control; refine focuses the items selector.
diff --git a/frontend/src/__tests__/ConfigStudio.test.tsx b/frontend/src/__tests__/ConfigStudio.test.tsx
index 2c6108b0..eaa9de52 100644
--- a/frontend/src/__tests__/ConfigStudio.test.tsx
+++ b/frontend/src/__tests__/ConfigStudio.test.tsx
@@ -75,6 +75,20 @@ function previewWithImage() {
 }
 
 describe('ConfigStudio', () => {
+  it('leads with the preview meadow above the items selector when live preview is ready', async () => {
+    echoValidate();
+    server.use(http.post('/api/v1/feeds/preview', () => HttpResponse.json(previewWithImage())));
+    renderStudio();
+
+    await waitFor(() => expect(screen.getByText('With image')).toBeInTheDocument(), { timeout: 4000 });
+
+    const meadow = screen.getByLabelText(COPY.previewRegion);
+    const items = screen.getByLabelText(COPY.itemsSelector);
+    expect(meadow.compareDocumentPosition(items) & Node.DOCUMENT_POSITION_FOLLOWING).not.toBe(0);
+    expect(document.querySelector('.result-shell')).toHaveAttribute('data-state', 'refine');
+    expect(document.querySelector('.ui-card')).toBeNull();
+  });
+
   it('focuses the items selector on a single-rail meadow with an editable URL', async () => {
     renderStudio();
 
diff --git a/frontend/src/components/ConfigStudio.tsx b/frontend/src/components/ConfigStudio.tsx
index e53509f9..40520fee 100644
--- a/frontend/src/components/ConfigStudio.tsx
+++ b/frontend/src/components/ConfigStudio.tsx
@@ -106,146 +106,156 @@ export function ConfigStudio({ url, token, onUrlChange, onUrlCleared, onGenerate
 
   return (
     <section
-      class="ui-card ui-card--padded ui-card--framed layout-rail-reading layout-stack"
+      class="result-shell layout-stack"
       data-state="refine"
       aria-labelledby="refine-title"
       aria-busy={isBusy}
     >
-      <h1 id="refine-title" class="ui-display-title">
-        {COPY.refineSelectors}
-      </h1>
+      <header class="layout-rail-reading layout-stack layout-stack--tight">
+        <h1 id="refine-title" class="ui-display-title">
+          {COPY.refineSelectors}
+        </h1>
+      </header>
 
-      <label class="field-block" htmlFor="studio-url">
-        <span class="ui-eyebrow">{COPY.urlLabel}</span>
-        <input
-          id="studio-url"
-          class="input input--mono"
-          type="url"
-          value={urlDraft}
-          spellcheck={false}
-          autoComplete="url"
-          onInput={(event) => setUrlDraft(inputValue(event))}
-          onBlur={onUrlBlur}
-        />
-      </label>
-
-      {nativeFeedUrl ? (
-        <Notice title={COPY.nativeFeedTitle}>
-          <a class="input--mono" href={nativeFeedUrl} target="_blank" rel="noopener noreferrer">
-            {nativeFeedUrl}
-          </a>
-        </Notice>
-      ) : undefined}
-
-      {state.phase === 'failed' ? (
-        <Notice title={COPY.createFailedTitle} tone="error">
-          {state.message.trim() && state.message !== COPY.createFailedTitle ? (
-            <p>{state.message}</p>
-          ) : undefined}
-        </Notice>
-      ) : undefined}
-
-      <label class="field-block" htmlFor="studio-items-selector">
-        <span class="ui-eyebrow">{COPY.itemsSelector}</span>
-        <input
-          id="studio-items-selector"
-          class="input input--mono input--lg"
-          value={state.draft.itemsSelector}
-          autoFocus
-          ref={itemsReference}
-          spellcheck={false}
-          onInput={(event) => studio.setItemsSelector(inputValue(event))}
-        />
-        <FieldErrors messages={messagesFor(issues, (issue) => issuePlace(issue.path).kind === 'items')} />
-      </label>
+      <PreviewPane
+        state={state}
+        token={token}
+        openField={openField}
+        onOpenField={openFieldPanel}
+        onRetry={studio.retryPreview}
+      />
 
-      <button type="button" class="btn btn--quiet" onClick={() => studio.requestSuggestion()}>
-        {COPY.applySuggestion}
-      </button>
+      <div class="layout-rail-reading layout-stack refine-controls">
+        {state.phase === 'failed' ? (
+          <Notice title={COPY.createFailedTitle} tone="error">
+            {state.message.trim() && state.message !== COPY.createFailedTitle ? (
+              <p>{state.message}</p>
+            ) : undefined}
+          </Notice>
+        ) : undefined}
 
-      <div class="refine-enhance">
-        <label class="refine-enhance__label" htmlFor="studio-enhance">
-          <span class="ui-eyebrow">{COPY.enhanceItems}</span>
+        <label class="field-block" htmlFor="studio-items-selector">
+          <span class="ui-eyebrow">{COPY.itemsSelector}</span>
           <input
-            id="studio-enhance"
-            class="refine-check"
-            type="checkbox"
-            checked={state.draft.enhance}
-            onChange={(event) => studio.setEnhance(isInputChecked(event))}
+            id="studio-items-selector"
+            class="input input--mono input--lg"
+            value={state.draft.itemsSelector}
+            autoFocus
+            ref={itemsReference}
+            spellcheck={false}
+            onInput={(event) => studio.setItemsSelector(inputValue(event))}
           />
+          <FieldErrors messages={messagesFor(issues, (issue) => issuePlace(issue.path).kind === 'items')} />
         </label>
-        <FieldErrors messages={messagesFor(issues, (issue) => issuePlace(issue.path).kind === 'enhance')} />
-      </div>
 
-      {hiddenIssues.length > 0 ? (
-        <button type="button" class="btn btn--quiet btn--linkish" onClick={onHiddenIssues}>
-          {COPY.issueCount(hiddenIssues.length)}
-        </button>
-      ) : undefined}
+        <div class="refine-controls__actions">
+          <button type="button" class="btn btn--quiet" onClick={() => studio.requestSuggestion()}>
+            {COPY.applySuggestion}
+          </button>
+        </div>
 
-      {panel ? (
-        <FieldFixPanel
-          field={panel.field}
-          selector={state.draft.fields[panel.field].selector}
-          selectorMessages={fieldMessages(issues, panel.field)}
-          onSelector={(selector) => studio.setFieldSelector(panel.field, selector)}
-        />
-      ) : undefined}
+        <div class="refine-enhance">
+          <label class="refine-enhance__label" htmlFor="studio-enhance">
+            <input
+              id="studio-enhance"
+              class="refine-check"
+              type="checkbox"
+              checked={state.draft.enhance}
+              onChange={(event) => studio.setEnhance(isInputChecked(event))}
+            />
+            <span class="refine-enhance__copy">
+              <span class="ui-eyebrow">{COPY.enhanceItems}</span>
+            </span>
+          </label>
+          <FieldErrors messages={messagesFor(issues, (issue) => issuePlace(issue.path).kind === 'enhance')} />
+        </div>
 
-      {showUnmapped && unmappedIssues.length > 0 ? (
-        <Notice tone="error">
-          {unmappedIssues.map((issue) => (
-            <p key={issueKey(issue)}>{issue.message}</p>
-          ))}
-        </Notice>
-      ) : undefined}
+        {hiddenIssues.length > 0 ? (
+          <button type="button" class="btn btn--quiet btn--linkish" onClick={onHiddenIssues}>
+            {COPY.issueCount(hiddenIssues.length)}
+          </button>
+        ) : undefined}
 
-      <div class="ui-actions">
-        <button
-          type="button"
-          class="btn btn--primary"
-          disabled={!canSaveStudio(state)}
-          onClick={() => {
-            if (!flushUrlBeforeSave()) return;
-            void studio.save(onGenerate);
-          }}
-        >
-          {state.phase === 'saving' ? COPY.creating : COPY.saveAndGenerate}
-        </button>
-      </div>
+        {panel ? (
+          <FieldFixPanel
+            field={panel.field}
+            selector={state.draft.fields[panel.field].selector}
+            selectorMessages={fieldMessages(issues, panel.field)}
+            onSelector={(selector) => studio.setFieldSelector(panel.field, selector)}
+          />
+        ) : undefined}
 
-      <div class="layout-stack layout-stack--tight">
-        <button
-          type="button"
-          class="btn btn--quiet btn--linkish"
-          onClick={() => setYamlOpen((open) => !open)}
-        >
-          {COPY.viewAsYaml}
-        </button>
-        {yamlOpen ? (
-          <>
-            <pre class="refine-yaml input input--mono">{state.yaml}</pre>
-            <button
-              type="button"
-              class="btn btn--quiet btn--linkish"
-              onClick={() => {
-                void copyYaml(state.yaml, setCopied, copyResetReference);
-              }}
-            >
-              {copied ? COPY.copied : COPY.copy}
-            </button>
-            <p class="field-help">{COPY.yamlFragmentCaption}</p>
-          </>
+        {showUnmapped && unmappedIssues.length > 0 ? (
+          <Notice tone="error">
+            {unmappedIssues.map((issue) => (
+              <p key={issueKey(issue)}>{issue.message}</p>
+            ))}
+          </Notice>
         ) : undefined}
+
+        <div class="ui-actions">
+          <button
+            type="button"
+            class="btn btn--primary"
+            disabled={!canSaveStudio(state)}
+            onClick={() => {
+              if (!flushUrlBeforeSave()) return;
+              void studio.save(onGenerate);
+            }}
+          >
+            {state.phase === 'saving' ? COPY.creating : COPY.saveAndGenerate}
+          </button>
+        </div>
       </div>
 
-      <PreviewPane
-        state={state}
-        token={token}
-        openField={openField}
-        onOpenField={openFieldPanel}
-        onRetry={studio.retryPreview}
-      />
+      <div class="layout-rail-reading layout-stack layout-stack--tight refine-support">
+        <label class="field-block" htmlFor="studio-url">
+          <span class="ui-eyebrow">{COPY.urlLabel}</span>
+          <input
+            id="studio-url"
+            class="input input--mono"
+            type="url"
+            value={urlDraft}
+            spellcheck={false}
+            autoComplete="url"
+            onInput={(event) => setUrlDraft(inputValue(event))}
+            onBlur={onUrlBlur}
+          />
+        </label>
+
+        {nativeFeedUrl ? (
+          <Notice title={COPY.nativeFeedTitle}>
+            <a class="input--mono" href={nativeFeedUrl} target="_blank" rel="noopener noreferrer">
+              {nativeFeedUrl}
+            </a>
+          </Notice>
+        ) : undefined}
+
+        <div class="layout-stack layout-stack--tight">
+          <button
+            type="button"
+            class="btn btn--quiet btn--linkish"
+            onClick={() => setYamlOpen((open) => !open)}
+          >
+            {COPY.viewAsYaml}
+          </button>
+          {yamlOpen ? (
+            <>
+              <pre class="refine-yaml input input--mono">{state.yaml}</pre>
+              <button
+                type="button"
+                class="btn btn--quiet btn--linkish"
+                onClick={() => {
+                  void copyYaml(state.yaml, setCopied, copyResetReference);
+                }}
+              >
+                {copied ? COPY.copied : COPY.copy}
+              </button>
+              <p class="field-help">{COPY.yamlFragmentCaption}</p>
+            </>
+          ) : undefined}
+        </div>
+      </div>
     </section>
   );
 }
@@ -267,7 +277,7 @@ function PreviewPane({
   const canShowImages = token.trim().length > 0;
 
   return (
-    <div class="layout-stack" aria-label={COPY.previewRegion}>
+    <div class="layout-rail-reading layout-stack" aria-label={COPY.previewRegion}>
       <p class="field-help">{COPY.previewFetchedCaption}</p>
       <div class="refine-status" role="group" aria-label={COPY.previewStatus}>
         {STUDIO_FIELDS.map((field) => {
diff --git a/frontend/src/styles/main.css b/frontend/src/styles/main.css
index 9ad77bf8..2c44bc91 100644
--- a/frontend/src/styles/main.css
+++ b/frontend/src/styles/main.css
@@ -572,25 +572,47 @@
   }
 }
 
+.refine-controls__actions {
+  display: flex;
+  justify-content: flex-start;
+}
+
 .refine-enhance {
   display: flex;
   flex-direction: column;
-  align-items: flex-start;
+  align-items: stretch;
   gap: var(--space-1);
 }
 
 .refine-enhance__label {
   display: flex;
-  flex-wrap: wrap;
   align-items: center;
-  gap: var(--space-2);
+  gap: var(--space-3);
+  min-height: calc(var(--space-7) + var(--space-3));
+  padding: var(--space-3);
+  border: var(--border-width) solid var(--border-subtle);
+  border-radius: var(--radius-md);
+  cursor: pointer;
+}
+
+.refine-enhance__copy {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-1);
+  min-width: 0;
 }
 
 .refine-check {
-  width: auto;
+  flex: 0 0 auto;
+  width: var(--space-4);
+  height: var(--space-4);
   margin: 0;
 }
 
+.refine-support {
+  opacity: 0.92;
+}
+
 .refine-sample-image {
   display: block;
   width: 100%;

From 3dc5964f56d4348133e8beb126ba80477850cb65 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 20 Sep 2026 11:50:10 +0200
Subject: [PATCH 046/108] test(studio): cover typed refine preview-first path

---
 frontend/e2e/smoke.spec.ts                   | 26 ++++++++++++++++----
 frontend/src/__tests__/App.contract.test.tsx |  2 ++
 2 files changed, 23 insertions(+), 5 deletions(-)

diff --git a/frontend/e2e/smoke.spec.ts b/frontend/e2e/smoke.spec.ts
index 9aa1ab6b..84d7ea84 100644
--- a/frontend/e2e/smoke.spec.ts
+++ b/frontend/e2e/smoke.spec.ts
@@ -244,8 +244,14 @@ test.describe('frontend smoke', () => {
     await fulfillJson(page, API_STUDIO_PREVIEW, {
       success: true,
       data: {
-        item_count: 0,
-        sample_items: [],
+        item_count: 1,
+        sample_items: [
+          {
+            title: 'Refine meadow item',
+            url: 'https://example.com/refine-item',
+            published_at: '2024-01-02',
+          },
+        ],
         quality_report: { warnings: [], metrics: { short_title_count: 0 } },
         failure_kind: '',
         validation_issues: [],
@@ -263,9 +269,19 @@ test.describe('frontend smoke', () => {
 
     await page.getByRole('button', { name: COPY.refineSelectors }).click();
     await expect(page).toHaveURL(/\/#\/refine$/);
-    await expect(page.getByLabel(COPY.itemsSelector)).toBeVisible();
-    await expect(page.getByLabel(COPY.itemsSelector)).not.toHaveValue('');
-    await expect(page.getByRole('button', { name: COPY.fieldMissing(COPY.fieldTitle) })).toBeVisible();
+    await expect(page.locator('.result-shell[data-state="refine"]')).toBeVisible();
+    await expect(page.locator('.ui-card')).toHaveCount(0);
+    await expect(page.getByText('Refine meadow item')).toBeVisible();
+    const meadow = page.getByLabel(COPY.previewRegion);
+    const items = page.getByLabel(COPY.itemsSelector);
+    await expect(items).toBeVisible();
+    await expect(items).not.toHaveValue('');
+    const meadowBox = await meadow.boundingBox();
+    const itemsBox = await items.boundingBox();
+    expect(meadowBox && itemsBox && meadowBox.y < itemsBox.y).toBe(true);
+    const enhanceBox = await page.getByLabel(COPY.enhanceItems).boundingBox();
+    expect(enhanceBox && enhanceBox.height >= 40).toBe(true);
+    await expect(page.getByRole('button', { name: COPY.fieldFound(COPY.fieldTitle) })).toBeVisible();
     await expect(page.locator('textarea')).toHaveCount(0);
     await expect(page.getByRole('combobox')).toHaveCount(0);
     const save = page.getByRole('button', { name: COPY.saveAndGenerate });
diff --git a/frontend/src/__tests__/App.contract.test.tsx b/frontend/src/__tests__/App.contract.test.tsx
index 76461ec5..f0094708 100644
--- a/frontend/src/__tests__/App.contract.test.tsx
+++ b/frontend/src/__tests__/App.contract.test.tsx
@@ -215,6 +215,8 @@ describe('App contract', () => {
 
     const save = await screen.findByRole('button', { name: COPY.saveAndGenerate });
     await waitFor(() => expect(save).toBeEnabled());
+    expect(document.querySelector('.result-shell')).toHaveAttribute('data-state', 'refine');
+    expect(document.querySelector('.ui-card')).toBeNull();
     fireEvent.click(save);
 
     await screen.findByText(COPY.feedReady);

From b20ffe6f7f50c5ada6d0d0b06b524ada419abaae Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 20 Sep 2026 11:53:41 +0200
Subject: [PATCH 047/108] chore(studio): clear ready-gate lint for stamped
 OpenAPI schemas

---
 frontend/src/studio/selectorDraft.ts          |  53 +++----
 spec/html2rss/web/api/v1_spec.rb              |  37 +++--
 spec/support/openapi.rb                       | 120 +---------------
 spec/support/openapi_runtime_contract_spec.rb |  23 ++-
 spec/support/openapi_studio_schemas.rb        | 136 ++++++++++++++++++
 5 files changed, 194 insertions(+), 175 deletions(-)
 create mode 100644 spec/support/openapi_studio_schemas.rb

diff --git a/frontend/src/studio/selectorDraft.ts b/frontend/src/studio/selectorDraft.ts
index e1b462e9..a120ab3f 100644
--- a/frontend/src/studio/selectorDraft.ts
+++ b/frontend/src/studio/selectorDraft.ts
@@ -54,24 +54,9 @@ export function selectorsFromDraft(draft: StudioDraft): RefinedSelectorsDocument
       : { selector: draft.itemsSelector },
   };
 
-  for (const field of STUDIO_FIELDS) {
-    const wire = fieldToWire(draft.fields[field], field);
-    if (!wire) continue;
-    switch (field) {
-      case 'title': {
-        selectors.title = wire;
-        break;
-      }
-      case 'link': {
-        selectors.url = wire;
-        break;
-      }
-      case 'published': {
-        selectors.published_at = wire;
-        break;
-      }
-    }
-  }
+  assignTextField(selectors, 'title', draft.fields.title.selector);
+  assignHrefField(selectors, draft.fields.link.selector);
+  assignTextField(selectors, 'published_at', draft.fields.published.selector);
 
   return selectors;
 }
@@ -82,7 +67,7 @@ export function draftFromSelectors(value: unknown): StudioDraft | undefined {
   const items = isPlainRecord(value.items) ? value.items : undefined;
   const fields = emptyFields();
   for (const key of ['title', 'url', 'published_at'] as const) {
-    if (!(key in value)) continue;
+    if (!Object.hasOwn(value, key)) continue;
     const parsed = parseField(key, value[key]);
     if (!parsed) return;
     fields[parsed.field] = parsed.draft;
@@ -139,6 +124,20 @@ function blankField(): FieldDraft {
   return { selector: '' };
 }
 
+function assignTextField(
+  selectors: RefinedSelectorsDocument,
+  key: 'title' | 'published_at',
+  selector: string
+): void {
+  if (selector.length === 0) return;
+  selectors[key] = { selector, extractor: 'text' };
+}
+
+function assignHrefField(selectors: RefinedSelectorsDocument, selector: string): void {
+  if (selector.length === 0) return;
+  selectors.url = { selector, extractor: 'href' };
+}
+
 function mapField(
   draft: StudioDraft,
   field: StudioFieldId,
@@ -153,22 +152,6 @@ function mapField(
   };
 }
 
-function fieldToWire(
-  field: FieldDraft,
-  id: StudioFieldId
-): RefinedSelectorsDocument['title'] | RefinedSelectorsDocument['url'] | undefined {
-  if (field.selector.length === 0) return;
-  switch (id) {
-    case 'link': {
-      return { selector: field.selector, extractor: 'href' };
-    }
-    case 'title':
-    case 'published': {
-      return { selector: field.selector, extractor: 'text' };
-    }
-  }
-}
-
 function parseField(
   key: 'title' | 'url' | 'published_at',
   value: unknown
diff --git a/spec/html2rss/web/api/v1_spec.rb b/spec/html2rss/web/api/v1_spec.rb
index 0e90b4a9..eb20a6a8 100644
--- a/spec/html2rss/web/api/v1_spec.rb
+++ b/spec/html2rss/web/api/v1_spec.rb
@@ -737,20 +737,18 @@ def relative_feed_link_header(token)
     }
 
     it 'signs optional refined selectors into the feed token', :aggregate_failures do
-      post_feed_request(
-        url: feed_url,
-        selectors: {
-          items: { selector: 'article', enhance: true },
-          title: { selector: 'h2', extractor: 'text' },
-          url: { selector: 'a', extractor: 'href' },
-          published_at: { selector: 'time', extractor: 'text' }
-        }
-      )
+      selectors = {
+        items: { selector: 'article', enhance: true },
+        title: { selector: 'h2', extractor: 'text' },
+        url: { selector: 'a', extractor: 'href' },
+        published_at: { selector: 'time', extractor: 'text' }
+      }
+      post_feed_request(url: feed_url, selectors:)
 
       token = expect_success_response(last_response).dig('data', 'feed', 'feed_token')
-      decoded = Html2rss::Web::Auth.validate_and_decode_feed_token(token)
-      expect(decoded.selectors.to_config_fragment.dig(:selectors, :items, :selector)).to eq('article')
-      expect(decoded.selectors.to_config_fragment.dig(:selectors, :title, :extractor)).to eq('text')
+      fragment = Html2rss::Web::Auth.validate_and_decode_feed_token(token).selectors.to_config_fragment
+      expect(fragment.dig(:selectors, :items, :selector)).to eq('article')
+      expect(fragment.dig(:selectors, :title, :extractor)).to eq('text')
     end
 
     it 'creates a feed when request is valid', :aggregate_failures do
@@ -905,14 +903,13 @@ def post_validate(payload)
     }
 
     it 'returns a structured report for an allowlisted selectors object', :aggregate_failures do
-      post_validate(
-        selectors: {
-          items: { selector: 'article', enhance: true },
-          title: { selector: 'h2', extractor: 'text' },
-          url: { selector: 'a', extractor: 'href' },
-          published_at: { selector: 'time', extractor: 'text' }
-        }
-      )
+      selectors = {
+        items: { selector: 'article', enhance: true },
+        title: { selector: 'h2', extractor: 'text' },
+        url: { selector: 'a', extractor: 'href' },
+        published_at: { selector: 'time', extractor: 'text' }
+      }
+      post_validate(selectors:)
 
       json = expect_success_response(last_response)
       expect(json.dig('data', 'report', 'success')).to be(true)
diff --git a/spec/support/openapi.rb b/spec/support/openapi.rb
index 76c8859b..d6d96415 100644
--- a/spec/support/openapi.rb
+++ b/spec/support/openapi.rb
@@ -74,124 +74,8 @@ def publish_allowed_keys(spec)
       'enum' => Html2rss::Web::RefinedSelectors::ALLOWED_KEYS.map(&:to_s).sort,
       'type' => 'string'
     }
-    schemas['RefinedSelectorsDocument'] = refined_selectors_document
-    schemas['PreviewSampleItem'] = preview_sample_item
-    rewrite_studio_refs(spec)
-  end
-
-  # Closed selectors subtree the SPA may author. No post_process; enhance is
-  # omitted when false.
-  #
-  # @return [Hash]
-  def refined_selectors_document
-    {
-      'description' => 'Allowlisted selectors document for create, validate, and preview.',
-      'type' => 'object',
-      'required' => %w[items],
-      'additionalProperties' => false,
-      'properties' => {
-        'items' => {
-          'type' => 'object',
-          'required' => %w[selector],
-          'additionalProperties' => false,
-          'properties' => {
-            'selector' => { 'type' => 'string' },
-            'enhance' => { 'type' => 'boolean' }
-          }
-        },
-        'title' => refined_field(%w[text]),
-        'url' => refined_field(%w[href]),
-        'published_at' => refined_field(%w[text])
-      }
-    }
-  end
-
-  # @param extractors [Array<String>]
-  # @return [Hash]
-  def refined_field(extractors)
-    {
-      'type' => 'object',
-      'required' => %w[selector extractor],
-      'additionalProperties' => false,
-      'properties' => {
-        'selector' => { 'type' => 'string' },
-        'extractor' => { 'type' => 'string', 'enum' => extractors }
-      }
-    }
-  end
-
-  # @return [Hash]
-  def preview_sample_item
-    {
-      'description' => 'One preview meadow row returned by POST /feeds/preview.',
-      'type' => 'object',
-      'required' => %w[title],
-      'properties' => {
-        'title' => { 'type' => 'string' },
-        'url' => { 'type' => 'string', 'nullable' => true },
-        'published_at' => { 'type' => 'string', 'nullable' => true },
-        'image' => { 'type' => 'string', 'nullable' => true }
-      }
-    }
-  end
-
-  # Replace example-inferred items-only hulls with the stamped closed schemas.
-  #
-  # @param spec [Hash]
-  # @return [void]
-  def rewrite_studio_refs(spec)
-    walk(spec) do |node|
-      properties = node['properties']
-      next unless properties.is_a?(Hash)
-
-      rewrite_selectors_property(properties)
-      rewrite_sample_items_property(properties)
-    end
-  end
-
-  # @param properties [Hash]
-  # @return [void]
-  def rewrite_selectors_property(properties)
-    schema = properties['selectors']
-    return unless selectors_document_hull?(schema)
-
-    properties['selectors'] = if schema['nullable']
-                                {
-                                  'allOf' => [{ '$ref' => '#/components/schemas/RefinedSelectorsDocument' }],
-                                  'nullable' => true
-                                }
-                              else
-                                { '$ref' => '#/components/schemas/RefinedSelectorsDocument' }
-                              end
-  end
-
-  # @param properties [Hash]
-  # @return [void]
-  def rewrite_sample_items_property(properties)
-    schema = properties['sample_items']
-    return unless sample_items_hull?(schema)
-
-    properties['sample_items'] = {
-      'type' => 'array',
-      'items' => { '$ref' => '#/components/schemas/PreviewSampleItem' }
-    }
-  end
-
-  # @param schema [Object]
-  # @return [Boolean]
-  def selectors_document_hull?(schema)
-    return false unless schema.is_a?(Hash)
-
-    items = schema.dig('properties', 'items')
-    items.is_a?(Hash) && items.dig('properties', 'selector').is_a?(Hash)
-  end
-
-  # @param schema [Object]
-  # @return [Boolean]
-  def sample_items_hull?(schema)
-    return false unless schema.is_a?(Hash) && schema['type'] == 'array'
-
-    schema.dig('items', 'properties', 'title').is_a?(Hash)
+    OpenapiStudioSchemas.publish(schemas)
+    OpenapiStudioSchemas.rewrite(spec)
   end
 
   # rspec-openapi seeds `components` symbol-keyed (`securitySchemes`), so a
diff --git a/spec/support/openapi_runtime_contract_spec.rb b/spec/support/openapi_runtime_contract_spec.rb
index 9fd4c2ce..63fb4e97 100644
--- a/spec/support/openapi_runtime_contract_spec.rb
+++ b/spec/support/openapi_runtime_contract_spec.rb
@@ -3,8 +3,9 @@
 require 'spec_helper'
 
 RSpec.describe OpenapiRuntimeContract do
-  it 'publishes the closed refined selectors document and preview sample item', :aggregate_failures do
-    spec = {
+  # rubocop:disable-next Metrics/MethodLength -- dense OpenAPI hull fixture
+  def studio_hull_spec
+    {
       'components' => { 'schemas' => {} },
       'paths' => {
         '/feeds/preview' => {
@@ -68,7 +69,10 @@
         }
       }
     }
+  end
 
+  it 'publishes closed refined selectors and preview sample schemas', :aggregate_failures do
+    spec = studio_hull_spec
     described_class.stamp(spec)
 
     document = spec.dig('components', 'schemas', 'RefinedSelectorsDocument')
@@ -79,12 +83,22 @@
 
     sample = spec.dig('components', 'schemas', 'PreviewSampleItem')
     expect(sample['properties'].keys).to include('title', 'url', 'published_at', 'image')
+  end
+
+  it 'rewrites request selectors hulls to the stamped document ref' do
+    spec = studio_hull_spec
+    described_class.stamp(spec)
 
     request_selectors = spec.dig(
       'paths', '/feeds/preview', 'post', 'requestBody', 'content', 'application/json',
       'schema', 'properties', 'selectors'
     )
     expect(request_selectors).to eq('$ref' => '#/components/schemas/RefinedSelectorsDocument')
+  end
+
+  it 'rewrites sample_items hulls to PreviewSampleItem' do
+    spec = studio_hull_spec
+    described_class.stamp(spec)
 
     sample_items = spec.dig(
       'paths', '/feeds/preview', 'post', 'responses', '200', 'content', 'application/json',
@@ -94,6 +108,11 @@
       'type' => 'array',
       'items' => { '$ref' => '#/components/schemas/PreviewSampleItem' }
     )
+  end
+
+  it 'rewrites nullable selector echoes with allOf refs' do
+    spec = studio_hull_spec
+    described_class.stamp(spec)
 
     echo = spec.dig(
       'paths', '/feeds/preview', 'post', 'responses', '200', 'content', 'application/json',
diff --git a/spec/support/openapi_studio_schemas.rb b/spec/support/openapi_studio_schemas.rb
new file mode 100644
index 00000000..de3e4d01
--- /dev/null
+++ b/spec/support/openapi_studio_schemas.rb
@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+##
+# Closed studio selector / preview schemas stamped into the OpenAPI document.
+module OpenapiStudioSchemas
+  REFINED_SELECTORS_REF = { '$ref' => '#/components/schemas/RefinedSelectorsDocument' }.freeze
+  PREVIEW_SAMPLE_ITEM_REF = { '$ref' => '#/components/schemas/PreviewSampleItem' }.freeze
+
+  module_function
+
+  # @param extractors [Array<String>]
+  # @return [Hash]
+  def refined_field(extractors)
+    {
+      'type' => 'object',
+      'required' => %w[selector extractor],
+      'additionalProperties' => false,
+      'properties' => {
+        'selector' => { 'type' => 'string' },
+        'extractor' => { 'type' => 'string', 'enum' => extractors }
+      }
+    }
+  end
+
+  # @return [Hash]
+  def refined_selectors_document
+    {
+      'description' => 'Allowlisted selectors document for create, validate, and preview.',
+      'type' => 'object',
+      'required' => %w[items],
+      'additionalProperties' => false,
+      'properties' => refined_selector_properties
+    }
+  end
+
+  # @return [Hash]
+  def refined_selector_properties
+    {
+      'items' => refined_items_property,
+      'title' => refined_field(%w[text]),
+      'url' => refined_field(%w[href]),
+      'published_at' => refined_field(%w[text])
+    }
+  end
+
+  # @return [Hash]
+  def refined_items_property
+    {
+      'type' => 'object',
+      'required' => %w[selector],
+      'additionalProperties' => false,
+      'properties' => {
+        'selector' => { 'type' => 'string' },
+        'enhance' => { 'type' => 'boolean' }
+      }
+    }
+  end
+
+  # @return [Hash]
+  def preview_sample_item
+    {
+      'description' => 'One preview meadow row returned by POST /feeds/preview.',
+      'type' => 'object',
+      'required' => %w[title],
+      'properties' => preview_sample_properties
+    }
+  end
+
+  # @return [Hash]
+  def preview_sample_properties
+    {
+      'title' => { 'type' => 'string' },
+      'url' => { 'type' => 'string', 'nullable' => true },
+      'published_at' => { 'type' => 'string', 'nullable' => true },
+      'image' => { 'type' => 'string', 'nullable' => true }
+    }
+  end
+
+  # @param schemas [Hash]
+  # @return [void]
+  def publish(schemas)
+    schemas['RefinedSelectorsDocument'] = refined_selectors_document
+    schemas['PreviewSampleItem'] = preview_sample_item
+  end
+
+  # @param spec [Hash]
+  # @return [void]
+  def rewrite(spec)
+    OpenapiRuntimeContract.walk(spec) do |node|
+      properties = node['properties']
+      next unless properties.is_a?(Hash)
+
+      rewrite_selectors_property(properties)
+      rewrite_sample_items_property(properties)
+    end
+  end
+
+  # @param properties [Hash]
+  # @return [void]
+  def rewrite_selectors_property(properties)
+    schema = properties['selectors']
+    return unless selectors_document_hull?(schema)
+
+    properties['selectors'] = if schema['nullable']
+                                { 'allOf' => [REFINED_SELECTORS_REF], 'nullable' => true }
+                              else
+                                REFINED_SELECTORS_REF.dup
+                              end
+  end
+
+  # @param properties [Hash]
+  # @return [void]
+  def rewrite_sample_items_property(properties)
+    schema = properties['sample_items']
+    return unless sample_items_hull?(schema)
+
+    properties['sample_items'] = { 'type' => 'array', 'items' => PREVIEW_SAMPLE_ITEM_REF.dup }
+  end
+
+  # @param schema [Object]
+  # @return [Boolean]
+  def selectors_document_hull?(schema)
+    return false unless schema.is_a?(Hash)
+
+    items = schema.dig('properties', 'items')
+    items.is_a?(Hash) && items.dig('properties', 'selector').is_a?(Hash)
+  end
+
+  # @param schema [Object]
+  # @return [Boolean]
+  def sample_items_hull?(schema)
+    return false unless schema.is_a?(Hash) && schema['type'] == 'array'
+
+    schema.dig('items', 'properties', 'title').is_a?(Hash)
+  end
+end

From 814d502cd75a54154ed324426e883cd44ad0b4a1 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 20 Sep 2026 11:54:38 +0200
Subject: [PATCH 048/108] fix(openapi): give nullable refined selectors a type
 sibling

---
 public/openapi.yaml                           | 3 ++-
 spec/support/openapi_runtime_contract_spec.rb | 5 +++--
 spec/support/openapi_studio_schemas.rb        | 6 +++++-
 3 files changed, 10 insertions(+), 4 deletions(-)

diff --git a/public/openapi.yaml b/public/openapi.yaml
index 8896f901..7f2e065f 100644
--- a/public/openapi.yaml
+++ b/public/openapi.yaml
@@ -750,9 +750,10 @@ paths:
                         - issues
                         type: object
                       selectors:
+                        type: object
+                        nullable: true
                         allOf:
                         - "$ref": "#/components/schemas/RefinedSelectorsDocument"
-                        nullable: true
                       yaml:
                         nullable: true
                         type: string
diff --git a/spec/support/openapi_runtime_contract_spec.rb b/spec/support/openapi_runtime_contract_spec.rb
index 63fb4e97..4e506018 100644
--- a/spec/support/openapi_runtime_contract_spec.rb
+++ b/spec/support/openapi_runtime_contract_spec.rb
@@ -119,8 +119,9 @@ def studio_hull_spec
       'schema', 'properties', 'data', 'properties', 'selectors'
     )
     expect(echo).to eq(
-      'allOf' => [{ '$ref' => '#/components/schemas/RefinedSelectorsDocument' }],
-      'nullable' => true
+      'type' => 'object',
+      'nullable' => true,
+      'allOf' => [{ '$ref' => '#/components/schemas/RefinedSelectorsDocument' }]
     )
   end
 end
diff --git a/spec/support/openapi_studio_schemas.rb b/spec/support/openapi_studio_schemas.rb
index de3e4d01..67a60e78 100644
--- a/spec/support/openapi_studio_schemas.rb
+++ b/spec/support/openapi_studio_schemas.rb
@@ -102,7 +102,11 @@ def rewrite_selectors_property(properties)
     return unless selectors_document_hull?(schema)
 
     properties['selectors'] = if schema['nullable']
-                                { 'allOf' => [REFINED_SELECTORS_REF], 'nullable' => true }
+                                {
+                                  'type' => 'object',
+                                  'nullable' => true,
+                                  'allOf' => [REFINED_SELECTORS_REF]
+                                }
                               else
                                 REFINED_SELECTORS_REF.dup
                               end

From d5a5d7f6715d0236e1ed4ce54c0a513883d16d6d Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 20 Sep 2026 11:54:56 +0200
Subject: [PATCH 049/108] chore(openapi): shorten nullable selectors stamp
 helper

---
 spec/support/openapi_studio_schemas.rb | 19 ++++++++++---------
 1 file changed, 10 insertions(+), 9 deletions(-)

diff --git a/spec/support/openapi_studio_schemas.rb b/spec/support/openapi_studio_schemas.rb
index 67a60e78..ecb2d69a 100644
--- a/spec/support/openapi_studio_schemas.rb
+++ b/spec/support/openapi_studio_schemas.rb
@@ -101,15 +101,16 @@ def rewrite_selectors_property(properties)
     schema = properties['selectors']
     return unless selectors_document_hull?(schema)
 
-    properties['selectors'] = if schema['nullable']
-                                {
-                                  'type' => 'object',
-                                  'nullable' => true,
-                                  'allOf' => [REFINED_SELECTORS_REF]
-                                }
-                              else
-                                REFINED_SELECTORS_REF.dup
-                              end
+    properties['selectors'] = schema['nullable'] ? nullable_selectors_schema : REFINED_SELECTORS_REF.dup
+  end
+
+  # @return [Hash]
+  def nullable_selectors_schema
+    {
+      'type' => 'object',
+      'nullable' => true,
+      'allOf' => [REFINED_SELECTORS_REF]
+    }
   end
 
   # @param properties [Hash]

From c375424a5803cf07220ca8f871c6ebb50f169925 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 20 Sep 2026 11:55:46 +0200
Subject: [PATCH 050/108] fix(e2e): disambiguate refine preview meadow locator

---
 frontend/e2e/smoke.spec.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/frontend/e2e/smoke.spec.ts b/frontend/e2e/smoke.spec.ts
index 84d7ea84..d58fe558 100644
--- a/frontend/e2e/smoke.spec.ts
+++ b/frontend/e2e/smoke.spec.ts
@@ -272,14 +272,14 @@ test.describe('frontend smoke', () => {
     await expect(page.locator('.result-shell[data-state="refine"]')).toBeVisible();
     await expect(page.locator('.ui-card')).toHaveCount(0);
     await expect(page.getByText('Refine meadow item')).toBeVisible();
-    const meadow = page.getByLabel(COPY.previewRegion);
+    const meadow = page.getByLabel(COPY.previewRegion, { exact: true });
     const items = page.getByLabel(COPY.itemsSelector);
     await expect(items).toBeVisible();
     await expect(items).not.toHaveValue('');
     const meadowBox = await meadow.boundingBox();
     const itemsBox = await items.boundingBox();
     expect(meadowBox && itemsBox && meadowBox.y < itemsBox.y).toBe(true);
-    const enhanceBox = await page.getByLabel(COPY.enhanceItems).boundingBox();
+    const enhanceBox = await page.locator('.refine-enhance__label').boundingBox();
     expect(enhanceBox && enhanceBox.height >= 40).toBe(true);
     await expect(page.getByRole('button', { name: COPY.fieldFound(COPY.fieldTitle) })).toBeVisible();
     await expect(page.locator('textarea')).toHaveCount(0);

From 193eb67751b230572116b7e69408f118dc9b98b1 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 20 Sep 2026 12:08:22 +0200
Subject: [PATCH 051/108] refactor(frontend): compress app test scenarios

Consolidate create-shell mounts and repeated hook stubs into
file-local scenario helpers without dropping observable assertions.
---
 frontend/src/__tests__/App.test.tsx | 823 ++++++++--------------------
 1 file changed, 221 insertions(+), 602 deletions(-)

diff --git a/frontend/src/__tests__/App.test.tsx b/frontend/src/__tests__/App.test.tsx
index 4d95d4cf..431bec1c 100644
--- a/frontend/src/__tests__/App.test.tsx
+++ b/frontend/src/__tests__/App.test.tsx
@@ -31,6 +31,10 @@ const mockUseApiMetadata = useApiMetadata as any;
 const mockUseFeedCreation = useFeedCreation as any;
 const mockUseCatalogEntries = useCatalogEntries as any;
 
+const EXAMPLE_URL = 'https://example.com/articles';
+const DIRECTORY_HREF =
+  'https://html2rss.github.io/feed-directory/#!url=http%3A%2F%2Flocalhost%3A3000%2F';
+
 const catalogHook = (entries: unknown[] = [], starters?: string[]) => ({
   entries,
   starters: starters ?? entries.map((entry: any) => entry.id).slice(0, 3),
@@ -40,7 +44,7 @@ const mockCreatedFeedResult = {
   feed: {
     id: 'feed-123',
     name: 'Example Feed',
-    url: 'https://example.com/articles',
+    url: EXAMPLE_URL,
     feed_token: 'generated-token',
     public_url: '/api/v1/feeds/generated-token',
     json_public_url: '/api/v1/feeds/generated-token.json',
@@ -53,6 +57,53 @@ const mockCreatedFeedResult = {
   warnings: [],
 };
 
+type CatalogEntry = {
+  id: string;
+  path: string;
+  title: string;
+  description: string;
+  channelUrl: string;
+  parameterDefaults: Record<string, string>;
+  lastResult: { state: string };
+};
+
+function catalogEntry(
+  id: string,
+  title: string,
+  channelUrl: string,
+  path = `/${id}.rss`,
+  parameterDefaults: Record<string, string> = {}
+): CatalogEntry {
+  return {
+    id,
+    path,
+    title,
+    description: `${title} description.`,
+    channelUrl,
+    parameterDefaults,
+    lastResult: { state: 'unknown' },
+  };
+}
+
+const faoStarter = catalogEntry(
+  'fao.org/newsroom',
+  'FAO Newsroom',
+  'https://www.fao.org/newsroom'
+);
+const anthropicNews = catalogEntry(
+  'anthropic.com/news',
+  'Anthropic — News',
+  'https://www.anthropic.com/news'
+);
+const bbcMundo = catalogEntry('bbc.com/mundo', 'BBC — Mundo', 'https://www.bbc.com/mundo');
+const bbcSounds = catalogEntry(
+  'bbc.co.uk/available_episodes',
+  'BBC Sounds — Programme episodes',
+  'https://www.bbc.co.uk/programmes/%<id>s/episodes/player',
+  '/bbc.co.uk/available_episodes.rss',
+  { id: 'b006wkfp' }
+);
+
 async function expectCreateRemountedWithoutErrorChrome() {
   await waitFor(() => {
     expect(screen.queryByText(COPY.createFailedTitle)).not.toBeInTheDocument();
@@ -74,45 +125,95 @@ describe('App', () => {
   /** Mirrors useFeedCreation: reject sets error; clearError clears it (App mock was static). */
   let creationHookError: FeedCreationError | undefined;
 
-  beforeEach(() => {
-    vi.clearAllMocks();
-    creationHookError = undefined;
-    history.replaceState({}, '', 'http://localhost:3000/#/create');
-    localStorage.clear();
-    mockCreateFeed.mockResolvedValue(mockCreatedFeedResult);
-    mockClearCreationError.mockImplementation(() => {
-      creationHookError = undefined;
-    });
-    mockUseCatalogEntries.mockReturnValue(catalogHook());
-
+  function stubAccessToken(opts: { token?: string; hasToken?: boolean; error?: string } = {}) {
     mockUseAccessToken.mockReturnValue({
-      token: undefined,
-      hasToken: false,
+      token: opts.token,
+      hasToken: opts.hasToken ?? Boolean(opts.token),
       saveToken: mockSaveToken,
       clearToken: mockClearToken,
       isLoading: false,
-      error: undefined,
+      error: opts.error,
     });
+  }
 
+  function stubMetadata(
+    opts: {
+      creationEnabled?: boolean;
+      tokenRequired?: boolean;
+      studioEnabled?: boolean;
+      openapiUrl?: string;
+      error?: string;
+    } = {}
+  ) {
+    if (opts.error !== undefined) {
+      mockUseApiMetadata.mockReturnValue({
+        metadata: undefined,
+        isLoading: false,
+        error: opts.error,
+      });
+      return;
+    }
     mockUseApiMetadata.mockReturnValue({
       metadata: {
         api: {
           name: 'html2rss-web API',
           description: 'RESTful API for converting websites to RSS feeds',
-          openapi_url: 'https://example.test/openapi.yaml',
+          openapi_url: opts.openapiUrl ?? 'https://example.test/openapi.yaml',
         },
         instance: {
           feed_creation: {
-            enabled: true,
-            access_token_required: true,
+            enabled: opts.creationEnabled ?? true,
+            access_token_required: opts.tokenRequired ?? true,
           },
-          studio: { enabled: true },
+          studio: { enabled: opts.studioEnabled ?? true },
           catalog: { enabled: true, url: '/api/v1/configs' },
         },
       },
       isLoading: false,
       error: undefined,
     });
+  }
+
+  function stubCreation(opts: {
+    isCreating?: boolean;
+    result?: unknown;
+    error?: FeedCreationError;
+  } = {}) {
+    mockUseFeedCreation.mockReturnValue({
+      isCreating: opts.isCreating ?? false,
+      result: opts.result,
+      error: opts.error,
+      createFeed: mockCreateFeed,
+      clearError: mockClearCreationError,
+      clearResult: mockClearResult,
+      retryPreviewFetch: mockRetryPreviewFetch,
+    });
+  }
+
+  function fillUrl(url = EXAMPLE_URL) {
+    fireEvent.input(screen.getByLabelText(COPY.urlLabel), { target: { value: url } });
+  }
+
+  function clickCreate() {
+    fireEvent.click(screen.getByRole('button', { name: COPY.createFeed }));
+  }
+
+  function withMemberSession(token = 'saved-token') {
+    stubAccessToken({ token });
+  }
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    creationHookError = undefined;
+    history.replaceState({}, '', 'http://localhost:3000/#/create');
+    localStorage.clear();
+    mockCreateFeed.mockResolvedValue(mockCreatedFeedResult);
+    mockClearCreationError.mockImplementation(() => {
+      creationHookError = undefined;
+    });
+    mockUseCatalogEntries.mockReturnValue(catalogHook());
+    stubAccessToken();
+    stubMetadata();
 
     mockUseFeedCreation.mockImplementation(() => ({
       isCreating: false,
@@ -142,128 +243,75 @@ describe('App', () => {
   };
 
   async function renderCreateWithCreationError() {
-    mockUseApiMetadata.mockReturnValue({
-      metadata: {
-        api: {
-          name: 'html2rss-web API',
-          description: 'RESTful API for converting websites to RSS feeds',
-          openapi_url: 'https://example.test/openapi.yaml',
-        },
-        instance: {
-          feed_creation: {
-            enabled: true,
-            access_token_required: false,
-          },
-          studio: { enabled: true },
-          catalog: { enabled: true, url: '/api/v1/configs' },
-        },
-      },
-      isLoading: false,
-      error: undefined,
-    });
+    stubMetadata({ tokenRequired: false });
     mockCreateFeed.mockRejectedValue(creationFailure);
-
     render(<App />);
-
-    fireEvent.input(screen.getByLabelText(COPY.urlLabel), {
-      target: { value: 'https://example.com/articles' },
-    });
-    fireEvent.click(screen.getByRole('button', { name: COPY.createFeed }));
-
+    fillUrl();
+    clickCreate();
     await waitFor(() => {
       expect(screen.getByText(COPY.createFailedRetryTitle)).toBeInTheDocument();
     });
   }
 
-  it('renders the radical-simple create flow', () => {
+  function serverError(
+    message: string,
+    retryAction: 'primary' | 'alternate' | 'none' = 'primary'
+  ): FeedCreationError {
+    return {
+      kind: 'server',
+      code: 'INTERNAL_SERVER_ERROR',
+      retryable: retryAction !== 'none',
+      nextAction: retryAction === 'none' ? 'none' : 'retry',
+      retryAction,
+      message,
+    };
+  }
+
+  it('renders create shell with permissive URL field and autofocus', async () => {
     render(<App />);
 
     expect(screen.getByLabelText('html2rss')).toBeInTheDocument();
     expect(screen.getByRole('link', { name: 'html2rss' }).getAttribute('href')).toMatch(/#\/create$/);
-    expect(screen.getByLabelText(COPY.urlLabel)).toBeInTheDocument();
     expect(screen.queryByRole('combobox')).not.toBeInTheDocument();
     expect(screen.getByLabelText(COPY.utilities)).toBeInTheDocument();
     expect(screen.getByRole('link', { name: COPY.bookmarkletTitle })).toBeInTheDocument();
     expect(document.querySelector('.form-shell')).toHaveAttribute('data-state', 'create');
-  });
-
-  it('keeps the URL field permissive enough for hostname-only input', () => {
-    render(<App />);
 
     const urlInput = screen.getByLabelText(COPY.urlLabel);
-
     expect(urlInput).toHaveAttribute('type', 'text');
     expect(urlInput).toHaveAttribute('inputmode', 'url');
     expect(urlInput).toHaveAttribute('autocapitalize', 'off');
-  });
-
-  it('autofocuses the URL field', async () => {
-    render(<App />);
-
     await waitFor(() => {
-      expect(document.activeElement).toBe(screen.getByLabelText(COPY.urlLabel));
+      expect(document.activeElement).toBe(urlInput);
     });
   });
 
   it('submits create requests without exposing strategy selection', async () => {
-    mockUseAccessToken.mockReturnValue({
-      token: 'saved-token',
-      hasToken: true,
-      saveToken: mockSaveToken,
-      clearToken: mockClearToken,
-      isLoading: false,
-      error: undefined,
-    });
-
+    withMemberSession();
     render(<App />);
-
-    fireEvent.input(screen.getByLabelText(COPY.urlLabel), {
-      target: { value: 'https://example.com/articles' },
-    });
-    fireEvent.click(screen.getByRole('button', { name: COPY.createFeed }));
+    fillUrl();
+    clickCreate();
 
     await waitFor(() => {
-      expect(mockCreateFeed).toHaveBeenCalledWith('https://example.com/articles', 'saved-token');
+      expect(mockCreateFeed).toHaveBeenCalledWith(EXAMPLE_URL, 'saved-token');
     });
   });
 
   it('submits create requests when Enter is pressed on the URL field', async () => {
-    mockUseAccessToken.mockReturnValue({
-      token: 'saved-token',
-      hasToken: true,
-      saveToken: mockSaveToken,
-      clearToken: mockClearToken,
-      isLoading: false,
-      error: undefined,
-    });
-
+    withMemberSession();
     render(<App />);
-
-    fireEvent.input(screen.getByLabelText(COPY.urlLabel), {
-      target: { value: 'https://example.com/articles' },
-    });
+    fillUrl();
     fireEvent.keyDown(screen.getByLabelText(COPY.urlLabel), { key: 'Enter' });
 
     await waitFor(() => {
-      expect(mockCreateFeed).toHaveBeenCalledWith('https://example.com/articles', 'saved-token');
+      expect(mockCreateFeed).toHaveBeenCalledWith(EXAMPLE_URL, 'saved-token');
     });
   });
 
   it('does not submit extra create requests when Enter key-repeats', async () => {
-    mockUseAccessToken.mockReturnValue({
-      token: 'saved-token',
-      hasToken: true,
-      saveToken: mockSaveToken,
-      clearToken: mockClearToken,
-      isLoading: false,
-      error: undefined,
-    });
-
+    withMemberSession();
     render(<App />);
-
-    fireEvent.input(screen.getByLabelText(COPY.urlLabel), {
-      target: { value: 'https://example.com/articles' },
-    });
+    fillUrl();
     const urlField = screen.getByLabelText(COPY.urlLabel);
     fireEvent.keyDown(urlField, { key: 'Enter' });
     fireEvent.keyDown(urlField, { key: 'Enter', repeat: true });
@@ -272,31 +320,22 @@ describe('App', () => {
     await waitFor(() => {
       expect(mockCreateFeed).toHaveBeenCalledTimes(1);
     });
-    expect(mockCreateFeed).toHaveBeenCalledWith('https://example.com/articles', 'saved-token');
+    expect(mockCreateFeed).toHaveBeenCalledWith(EXAMPLE_URL, 'saved-token');
   });
 
   it('auto-submits a prefilled url without persisting strategy state', async () => {
-    mockUseAccessToken.mockReturnValue({
-      token: 'saved-token',
-      hasToken: true,
-      saveToken: mockSaveToken,
-      clearToken: mockClearToken,
-      isLoading: false,
-      error: undefined,
-    });
+    withMemberSession();
     history.replaceState({}, '', 'http://localhost:3000/?url=https%3A%2F%2Fexample.com%2Farticles');
-
     render(<App />);
 
     await waitFor(() => {
-      expect(mockCreateFeed).toHaveBeenCalledWith('https://example.com/articles', 'saved-token');
+      expect(mockCreateFeed).toHaveBeenCalledWith(EXAMPLE_URL, 'saved-token');
       expect(location.hash).toBe('#/result/generated-token');
     });
   });
 
   it('recovers unmatched result deep links onto remounted create without url prefill', async () => {
     history.replaceState({}, '', 'http://localhost:3000/#/result/generated-token');
-
     render(<App />);
 
     await waitFor(() => {
@@ -312,9 +351,7 @@ describe('App', () => {
   it('remounts create from BrandLockup and clears creation chrome', async () => {
     await renderCreateWithCreationError();
     const createCalls = mockCreateFeed.mock.calls.length;
-
     fireEvent.click(screen.getByRole('link', { name: 'html2rss' }));
-
     await expectCreateRemountedWithoutErrorChrome();
     expect(mockCreateFeed).toHaveBeenCalledTimes(createCalls);
   });
@@ -322,9 +359,7 @@ describe('App', () => {
   it('remounts create from a #/create visit and clears creation chrome', async () => {
     await renderCreateWithCreationError();
     const createCalls = mockCreateFeed.mock.calls.length;
-
     dispatchEvent(new HashChangeEvent('hashchange'));
-
     await expectCreateRemountedWithoutErrorChrome();
     expect(location.hash).toBe('#/create');
     expect(mockCreateFeed).toHaveBeenCalledTimes(createCalls);
@@ -333,9 +368,7 @@ describe('App', () => {
   it('remounts create from a hashbang entry and clears creation chrome', async () => {
     await renderCreateWithCreationError();
     const createCalls = mockCreateFeed.mock.calls.length;
-
     location.hash = '#!/create';
-
     await waitFor(() => {
       expect(location.hash).toBe('#/create');
     });
@@ -345,11 +378,8 @@ describe('App', () => {
 
   it('shows inline token prompt when submitting without a token', async () => {
     render(<App />);
-
-    fireEvent.input(screen.getByLabelText(COPY.urlLabel), {
-      target: { value: 'https://example.com/articles' },
-    });
-    fireEvent.click(screen.getByRole('button', { name: COPY.createFeed }));
+    fillUrl();
+    clickCreate();
 
     expect(screen.getByRole('heading', { name: COPY.tokenTitle })).toBeInTheDocument();
     expect(location.hash).toMatch(/^#\/token/);
@@ -369,27 +399,9 @@ describe('App', () => {
     expect(mockCreateFeed).not.toHaveBeenCalled();
   });
 
-  const faoStarter = {
-    id: 'fao.org/newsroom',
-    path: '/fao.org/newsroom.rss',
-    title: 'FAO Newsroom',
-    description: 'News and media from the Food and Agriculture Organization.',
-    channelUrl: 'https://www.fao.org/newsroom',
-    parameterDefaults: {},
-    lastResult: { state: 'unknown' },
-  };
-
   it('shows lean included-feed starters on empty create when creation is enabled', async () => {
     mockUseCatalogEntries.mockReturnValue(catalogHook([faoStarter], ['fao.org/newsroom']));
-    mockUseAccessToken.mockReturnValue({
-      token: 'session-token',
-      hasToken: true,
-      saveToken: mockSaveToken,
-      clearToken: mockClearToken,
-      isLoading: false,
-      error: undefined,
-    });
-
+    withMemberSession('session-token');
     render(<App />);
 
     await waitFor(() => {
@@ -407,10 +419,7 @@ describe('App', () => {
     const directoryLinks = screen.getAllByRole('link', { name: COPY.browseFeedDirectory(1) });
     expect(directoryLinks).toHaveLength(2);
     for (const link of directoryLinks) {
-      expect(link).toHaveAttribute(
-        'href',
-        'https://html2rss.github.io/feed-directory/#!url=http%3A%2F%2Flocalhost%3A3000%2F'
-      );
+      expect(link).toHaveAttribute('href', DIRECTORY_HREF);
       expect(link).toHaveClass('utility-link');
     }
     await waitFor(() => {
@@ -420,66 +429,31 @@ describe('App', () => {
 
   it('hides included-feed starters when the URL field is non-empty', async () => {
     mockUseCatalogEntries.mockReturnValue(catalogHook([faoStarter], ['fao.org/newsroom']));
-    mockUseAccessToken.mockReturnValue({
-      token: 'session-token',
-      hasToken: true,
-      saveToken: mockSaveToken,
-      clearToken: mockClearToken,
-      isLoading: false,
-      error: undefined,
-    });
-
+    withMemberSession('session-token');
     render(<App />);
 
     await waitFor(() => {
       expect(screen.getByRole('link', { name: 'FAO Newsroom' })).toBeInTheDocument();
     });
-
-    fireEvent.input(screen.getByLabelText(COPY.urlLabel), {
-      target: { value: 'example.com/articles' },
-    });
+    fillUrl('example.com/articles');
 
     expect(screen.queryByRole('link', { name: 'FAO Newsroom' })).not.toBeInTheDocument();
     expect(screen.queryByRole('list', { name: COPY.feedDirectory })).not.toBeInTheDocument();
     expect(screen.getByRole('link', { name: COPY.browseFeedDirectory(1) })).toHaveAttribute(
       'href',
-      'https://html2rss.github.io/feed-directory/#!url=http%3A%2F%2Flocalhost%3A3000%2F'
+      DIRECTORY_HREF
     );
   });
 
   it('hides included-feed starters when catalog find has hits', async () => {
-    mockUseCatalogEntries.mockReturnValue(
-      catalogHook([
-        faoStarter,
-        {
-          id: 'anthropic.com/news',
-          path: '/anthropic.com/news.rss',
-          title: 'Anthropic — News',
-          description: 'Product and research announcements from Anthropic.',
-          channelUrl: 'https://www.anthropic.com/news',
-          parameterDefaults: {},
-          lastResult: { state: 'unknown' },
-        },
-      ])
-    );
-    mockUseAccessToken.mockReturnValue({
-      token: 'session-token',
-      hasToken: true,
-      saveToken: mockSaveToken,
-      clearToken: mockClearToken,
-      isLoading: false,
-      error: undefined,
-    });
-
+    mockUseCatalogEntries.mockReturnValue(catalogHook([faoStarter, anthropicNews]));
+    withMemberSession('session-token');
     render(<App />);
 
     await waitFor(() => {
       expect(screen.getByRole('link', { name: 'FAO Newsroom' })).toBeInTheDocument();
     });
-
-    fireEvent.input(screen.getByLabelText(COPY.urlLabel), {
-      target: { value: 'www.anthropic.com/news' },
-    });
+    fillUrl('www.anthropic.com/news');
 
     await waitFor(() => {
       expect(screen.getByRole('option', { name: 'Anthropic — News' })).toBeInTheDocument();
@@ -491,27 +465,7 @@ describe('App', () => {
 
   it('promotes included feeds when feed creation is disabled', async () => {
     mockUseCatalogEntries.mockReturnValue(catalogHook([faoStarter], ['fao.org/newsroom']));
-
-    mockUseApiMetadata.mockReturnValue({
-      metadata: {
-        api: {
-          name: 'html2rss-web API',
-          description: 'RESTful API for converting websites to RSS feeds',
-          openapi_url: 'https://example.test/openapi.yaml',
-        },
-        instance: {
-          feed_creation: {
-            enabled: false,
-            access_token_required: false,
-          },
-          studio: { enabled: true },
-          catalog: { enabled: true, url: '/api/v1/configs' },
-        },
-      },
-      isLoading: false,
-      error: undefined,
-    });
-
+    stubMetadata({ creationEnabled: false, tokenRequired: false });
     render(<App />);
 
     await waitFor(() => {
@@ -531,25 +485,9 @@ describe('App', () => {
   });
 
   it('suggests included feeds when the URL matches the catalog', async () => {
-    mockUseCatalogEntries.mockReturnValue(
-      catalogHook([
-        {
-          id: 'anthropic.com/news',
-          path: '/anthropic.com/news.rss',
-          title: 'Anthropic — News',
-          description: 'Product and research announcements from Anthropic.',
-          channelUrl: 'https://www.anthropic.com/news',
-          parameterDefaults: {},
-          lastResult: { state: 'unknown' },
-        },
-      ])
-    );
-
+    mockUseCatalogEntries.mockReturnValue(catalogHook([anthropicNews]));
     render(<App />);
-
-    fireEvent.input(screen.getByLabelText(COPY.urlLabel), {
-      target: { value: 'www.anthropic.com/news' },
-    });
+    fillUrl('www.anthropic.com/news');
 
     await waitFor(() => {
       expect(screen.getByRole('option', { name: 'Anthropic — News' })).toHaveAttribute(
@@ -561,34 +499,9 @@ describe('App', () => {
   });
 
   it('lists multiple catalog find hits for a text query including defaults href', async () => {
-    mockUseCatalogEntries.mockReturnValue(
-      catalogHook([
-        {
-          id: 'bbc.com/mundo',
-          path: '/bbc.com/mundo.rss',
-          title: 'BBC — Mundo',
-          description: 'Spanish-language news from BBC Mundo.',
-          channelUrl: 'https://www.bbc.com/mundo',
-          parameterDefaults: {},
-          lastResult: { state: 'unknown' },
-        },
-        {
-          id: 'bbc.co.uk/available_episodes',
-          path: '/bbc.co.uk/available_episodes.rss',
-          title: 'BBC Sounds — Programme episodes',
-          description: 'Available episodes for a BBC programme on Sounds.',
-          channelUrl: 'https://www.bbc.co.uk/programmes/%<id>s/episodes/player',
-          parameterDefaults: { id: 'b006wkfp' },
-          lastResult: { state: 'unknown' },
-        },
-      ])
-    );
-
+    mockUseCatalogEntries.mockReturnValue(catalogHook([bbcMundo, bbcSounds]));
     render(<App />);
-
-    fireEvent.input(screen.getByLabelText(COPY.urlLabel), {
-      target: { value: 'bbc' },
-    });
+    fillUrl('bbc');
 
     await waitFor(() => {
       expect(screen.getByRole('option', { name: 'BBC — Mundo' })).toHaveAttribute(
@@ -600,7 +513,6 @@ describe('App', () => {
         '/bbc.co.uk/available_episodes.rss?id=b006wkfp'
       );
     });
-
     expect(screen.getByRole('option', { name: 'BBC — Mundo' })).toHaveClass('catalog-hit');
     expect(screen.getByRole('option', { name: 'BBC — Mundo' })).not.toHaveClass('ui-card');
     expect(screen.getByRole('listbox', { name: COPY.catalogFindHitsLabel })).toBeInTheDocument();
@@ -609,85 +521,35 @@ describe('App', () => {
   it('opens the active catalog hit with ArrowDown then Enter without submitting Create', async () => {
     const assignSpy = vi.fn();
     vi.stubGlobal('location', { ...location, assign: assignSpy });
-
-    mockUseCatalogEntries.mockReturnValue(
-      catalogHook([
-        {
-          id: 'bbc.com/mundo',
-          path: '/bbc.com/mundo.rss',
-          title: 'BBC — Mundo',
-          description: 'Spanish-language news from BBC Mundo.',
-          channelUrl: 'https://www.bbc.com/mundo',
-          parameterDefaults: {},
-          lastResult: { state: 'unknown' },
-        },
-        {
-          id: 'bbc.co.uk/available_episodes',
-          path: '/bbc.co.uk/available_episodes.rss',
-          title: 'BBC Sounds — Programme episodes',
-          description: 'Available episodes for a BBC programme on Sounds.',
-          channelUrl: 'https://www.bbc.co.uk/programmes/%<id>s/episodes/player',
-          parameterDefaults: { id: 'b006wkfp' },
-          lastResult: { state: 'unknown' },
-        },
-      ])
-    );
-
+    mockUseCatalogEntries.mockReturnValue(catalogHook([bbcMundo, bbcSounds]));
     render(<App />);
 
     const urlField = screen.getByLabelText(COPY.urlLabel);
     fireEvent.input(urlField, { target: { value: 'bbc' } });
-
     await waitFor(() => {
       expect(screen.getByRole('listbox', { name: COPY.catalogFindHitsLabel })).toBeInTheDocument();
     });
-
     fireEvent.keyDown(urlField, { key: 'ArrowDown' });
     await waitFor(() => {
       expect(urlField).toHaveAttribute('aria-activedescendant', 'catalog-find-hits-option-0');
     });
-
     fireEvent.keyDown(urlField, { key: 'Enter' });
 
     expect(assignSpy).toHaveBeenCalledWith('/bbc.co.uk/available_episodes.rss?id=b006wkfp');
     expect(mockCreateFeed).not.toHaveBeenCalled();
-
     vi.unstubAllGlobals();
   });
 
   it('submits Create with Enter when no catalog hit is active', async () => {
-    mockUseAccessToken.mockReturnValue({
-      token: 'saved-token',
-      hasToken: true,
-      saveToken: mockSaveToken,
-      clearToken: mockClearToken,
-      isLoading: false,
-      error: undefined,
-    });
-
-    mockUseCatalogEntries.mockReturnValue(
-      catalogHook([
-        {
-          id: 'bbc.com/mundo',
-          path: '/bbc.com/mundo.rss',
-          title: 'BBC — Mundo',
-          description: 'Spanish-language news from BBC Mundo.',
-          channelUrl: 'https://www.bbc.com/mundo',
-          parameterDefaults: {},
-          lastResult: { state: 'unknown' },
-        },
-      ])
-    );
-
+    withMemberSession();
+    mockUseCatalogEntries.mockReturnValue(catalogHook([bbcMundo]));
     render(<App />);
 
     const urlField = screen.getByLabelText(COPY.urlLabel);
     fireEvent.input(urlField, { target: { value: 'https://www.bbc.com/mundo' } });
-
     await waitFor(() => {
       expect(screen.getByRole('listbox', { name: COPY.catalogFindHitsLabel })).toBeInTheDocument();
     });
-
     fireEvent.keyDown(urlField, { key: 'Enter' });
 
     await waitFor(() => {
@@ -697,13 +559,12 @@ describe('App', () => {
 
   it('renders the result panel when a feed is available', async () => {
     history.replaceState({}, '', 'http://localhost:3000/#/result/example-token');
-    mockUseFeedCreation.mockReturnValue({
-      isCreating: false,
+    stubCreation({
       result: {
         feed: {
           id: 'feed-123',
           name: 'Example Feed',
-          url: 'https://example.com/articles',
+          url: EXAMPLE_URL,
           feed_token: 'example-token',
           public_url: '/api/v1/feeds/example-token',
           json_public_url: '/api/v1/feeds/example-token.json',
@@ -722,13 +583,7 @@ describe('App', () => {
           },
         ],
       },
-      error: undefined,
-      createFeed: mockCreateFeed,
-      clearError: mockClearCreationError,
-      clearResult: mockClearResult,
-      retryPreviewFetch: mockRetryPreviewFetch,
     });
-
     render(<App />);
 
     expect(document.querySelector('.result-shell')).toHaveAttribute('data-state', 'result');
@@ -738,31 +593,16 @@ describe('App', () => {
     expect(screen.getByText('Example Feed')).toBeInTheDocument();
     expect(screen.getByText(COPY.feedReady)).toBeInTheDocument();
     expect(screen.getByText(COPY.previewUnavailable)).toBeInTheDocument();
+    expect(screen.getByLabelText(COPY.utilities)).toBeInTheDocument();
 
     fireEvent.click(screen.getByRole('button', { name: COPY.createAnother }));
-    return waitFor(() => {
+    await waitFor(() => {
       expect(location.hash).toMatch(/^#\/create/);
     });
   });
 
   it('surfaces creation errors to the user', () => {
-    mockUseFeedCreation.mockReturnValue({
-      isCreating: false,
-      result: undefined,
-      error: {
-        kind: 'server',
-        code: 'INTERNAL_SERVER_ERROR',
-        retryable: true,
-        nextAction: 'retry',
-        retryAction: 'primary',
-        message: 'Access denied',
-      },
-      createFeed: mockCreateFeed,
-      clearError: mockClearCreationError,
-      clearResult: mockClearResult,
-      retryPreviewFetch: mockRetryPreviewFetch,
-    });
-
+    stubCreation({ error: serverError('Access denied') });
     render(<App />);
 
     expect(document.querySelector('.form-shell')).toHaveAttribute('data-state', 'error');
@@ -771,9 +611,7 @@ describe('App', () => {
   });
 
   it('presents classified create errors with the wire sentence', () => {
-    mockUseFeedCreation.mockReturnValue({
-      isCreating: false,
-      result: undefined,
+    stubCreation({
       error: {
         kind: 'input',
         code: 'BLOCKED_SURFACE',
@@ -782,12 +620,7 @@ describe('App', () => {
         retryAction: 'none',
         message: 'This site blocked automated access. Try another URL or site.',
       },
-      createFeed: mockCreateFeed,
-      clearError: mockClearCreationError,
-      clearResult: mockClearResult,
-      retryPreviewFetch: mockRetryPreviewFetch,
     });
-
     render(<App />);
 
     expect(screen.getByText(COPY.createFailedTitle)).toBeInTheDocument();
@@ -798,12 +631,7 @@ describe('App', () => {
   });
 
   it('shows instance metadata failure as a banner without create-error chrome', () => {
-    mockUseApiMetadata.mockReturnValue({
-      metadata: undefined,
-      isLoading: false,
-      error: 'Instance unavailable.',
-    });
-
+    stubMetadata({ error: 'Instance unavailable.' });
     render(<App />);
 
     expect(screen.getByText(COPY.instanceMetadataUnavailable)).toBeInTheDocument();
@@ -814,15 +642,7 @@ describe('App', () => {
   });
 
   it('shows access token load failure with a token title, not metadata heading', () => {
-    mockUseAccessToken.mockReturnValue({
-      token: undefined,
-      hasToken: false,
-      saveToken: mockSaveToken,
-      clearToken: mockClearToken,
-      isLoading: false,
-      error: COPY.unableToLoadToken,
-    });
-
+    stubAccessToken({ error: COPY.unableToLoadToken });
     render(<App />);
 
     expect(screen.getByText(COPY.accessTokenUnavailable)).toBeInTheDocument();
@@ -832,16 +652,7 @@ describe('App', () => {
   });
 
   it('shows title-only creating notice without preview copy', () => {
-    mockUseFeedCreation.mockReturnValue({
-      isCreating: true,
-      result: undefined,
-      error: undefined,
-      createFeed: mockCreateFeed,
-      clearError: mockClearCreationError,
-      clearResult: mockClearResult,
-      retryPreviewFetch: mockRetryPreviewFetch,
-    });
-
+    stubCreation({ isCreating: true });
     render(<App />);
 
     expect(screen.getByText(COPY.creating)).toBeInTheDocument();
@@ -849,17 +660,8 @@ describe('App', () => {
   });
 
   it('keeps the token dialog open while creating', () => {
-    mockUseFeedCreation.mockReturnValue({
-      isCreating: true,
-      result: undefined,
-      error: undefined,
-      createFeed: mockCreateFeed,
-      clearError: mockClearCreationError,
-      clearResult: mockClearResult,
-      retryPreviewFetch: mockRetryPreviewFetch,
-    });
+    stubCreation({ isCreating: true });
     history.replaceState({}, '', 'http://localhost:3000/#/token?url=https%3A%2F%2Fexample.com%2Farticles');
-
     render(<App />);
 
     expect(document.querySelector('dialog')).toHaveAttribute('open');
@@ -867,33 +669,8 @@ describe('App', () => {
     expect(screen.queryByText(COPY.createFailedTitle)).not.toBeInTheDocument();
   });
 
-  it('clears stored token from instance info', () => {
-    mockUseAccessToken.mockReturnValue({
-      token: 'saved-token',
-      hasToken: true,
-      saveToken: mockSaveToken,
-      clearToken: mockClearToken,
-      isLoading: false,
-      error: undefined,
-    });
-
-    render(<App />);
-
-    fireEvent.click(screen.getByRole('button', { name: COPY.logout }));
-
-    expect(mockClearToken).toHaveBeenCalled();
-  });
-
-  it('keeps the Docker Hub link before token clear when a token is saved', () => {
-    mockUseAccessToken.mockReturnValue({
-      token: 'saved-token',
-      hasToken: true,
-      saveToken: mockSaveToken,
-      clearToken: mockClearToken,
-      isLoading: false,
-      error: undefined,
-    });
-
+  it('clears stored token and keeps Docker Hub before logout in utilities', () => {
+    withMemberSession();
     render(<App />);
 
     const utilityItems = [
@@ -901,7 +678,6 @@ describe('App', () => {
         .getByLabelText(COPY.utilities)
         .querySelectorAll(':scope .utility-strip__items > a, :scope .utility-strip__items > button'),
     ].map((element) => element.textContent);
-
     expect(utilityItems).toEqual([
       COPY.browseFeedDirectory(),
       COPY.bookmarkletTitle,
@@ -910,34 +686,27 @@ describe('App', () => {
       COPY.openapiSpec,
       COPY.sourceCode,
     ]);
+
+    fireEvent.click(screen.getByRole('button', { name: COPY.logout }));
+    expect(mockClearToken).toHaveBeenCalled();
   });
 
   it('saves access token and resumes feed creation from the inline prompt', async () => {
     render(<App />);
-
-    fireEvent.input(screen.getByLabelText(COPY.urlLabel), {
-      target: { value: 'https://example.com/articles' },
-    });
-    fireEvent.click(screen.getByRole('button', { name: COPY.createFeed }));
+    fillUrl();
+    clickCreate();
     const accessTokenInput = document.querySelector('#access-token') as HTMLInputElement;
     fireEvent.input(accessTokenInput, { target: { value: 'token-123' } });
     fireEvent.click(screen.getByRole('button', { name: COPY.saveAndContinue }));
 
     await waitFor(() => {
       expect(mockSaveToken).toHaveBeenCalledWith('token-123');
-      expect(mockCreateFeed).toHaveBeenCalledWith('https://example.com/articles', 'token-123');
+      expect(mockCreateFeed).toHaveBeenCalledWith(EXAMPLE_URL, 'token-123');
     });
   });
 
   it('reopens the token prompt when a saved token is rejected', async () => {
-    mockUseAccessToken.mockReturnValue({
-      token: 'saved-token',
-      hasToken: true,
-      saveToken: mockSaveToken,
-      clearToken: mockClearToken,
-      isLoading: false,
-      error: undefined,
-    });
+    withMemberSession();
     mockCreateFeed.mockRejectedValueOnce(
       Object.assign(new Error('Unauthorized'), {
         code: 'UNAUTHORIZED',
@@ -945,13 +714,9 @@ describe('App', () => {
         kind: 'auth',
       })
     );
-
     render(<App />);
-
-    fireEvent.input(screen.getByLabelText(COPY.urlLabel), {
-      target: { value: 'https://example.com/articles' },
-    });
-    fireEvent.click(screen.getByRole('button', { name: COPY.createFeed }));
+    fillUrl();
+    clickCreate();
 
     await waitFor(() => {
       expect(screen.getByRole('heading', { name: COPY.tokenTitle })).toBeInTheDocument();
@@ -962,14 +727,7 @@ describe('App', () => {
   });
 
   it('clears stale creation error when backing out of the token gate', async () => {
-    mockUseAccessToken.mockReturnValue({
-      token: 'saved-token',
-      hasToken: true,
-      saveToken: mockSaveToken,
-      clearToken: mockClearToken,
-      isLoading: false,
-      error: undefined,
-    });
+    withMemberSession();
     mockCreateFeed.mockRejectedValueOnce(
       Object.assign(new Error('Unauthorized'), {
         code: 'UNAUTHORIZED',
@@ -977,13 +735,9 @@ describe('App', () => {
         kind: 'auth',
       })
     );
-
     render(<App />);
-
-    fireEvent.input(screen.getByLabelText(COPY.urlLabel), {
-      target: { value: 'https://example.com/articles' },
-    });
-    fireEvent.click(screen.getByRole('button', { name: COPY.createFeed }));
+    fillUrl();
+    clickCreate();
 
     await screen.findByText(COPY.tokenRejected);
     fireEvent.click(screen.getByRole('button', { name: COPY.back }));
@@ -997,12 +751,8 @@ describe('App', () => {
 
   it('submits the token prompt with Enter', async () => {
     render(<App />);
-
-    fireEvent.input(screen.getByLabelText(COPY.urlLabel), {
-      target: { value: 'https://example.com/articles' },
-    });
-    fireEvent.click(screen.getByRole('button', { name: COPY.createFeed }));
-
+    fillUrl();
+    clickCreate();
     const accessTokenInput = document.querySelector('#access-token') as HTMLInputElement;
     fireEvent.input(accessTokenInput, { target: { value: 'token-123' } });
     fireEvent.keyDown(accessTokenInput, { key: 'Enter' });
@@ -1013,9 +763,7 @@ describe('App', () => {
   });
 
   it('builds a bookmarklet that returns to the root app entry', () => {
-    history.replaceState({}, '', 'http://localhost:3000/#/create');
     render(<App />);
-
     const bookmarklet = screen.getByRole('link', { name: COPY.bookmarkletTitle });
     expect(bookmarklet.getAttribute('href')).toContain('/#/create?url=');
     expect(bookmarklet.getAttribute('href')).not.toContain('%27+encodeURIComponent');
@@ -1023,7 +771,6 @@ describe('App', () => {
 
   it('opens token entry immediately for bookmarklet urls when no token is saved', async () => {
     history.replaceState({}, '', 'http://localhost:3000/?url=example.com%2Farticles');
-
     render(<App />);
 
     await screen.findByRole('heading', { name: COPY.tokenTitle });
@@ -1031,18 +778,17 @@ describe('App', () => {
     expect(document.querySelector('dialog')).toHaveAttribute('open');
     expect(screen.getByLabelText(COPY.urlLabel)).toBeInTheDocument();
     await waitFor(() => {
-      expect(screen.getByLabelText(COPY.urlLabel)).toHaveValue('https://example.com/articles');
+      expect(screen.getByLabelText(COPY.urlLabel)).toHaveValue(EXAMPLE_URL);
     });
     expect(mockCreateFeed).not.toHaveBeenCalled();
   });
 
   it('prefills the URL field when landing with a bookmarklet hash route', async () => {
     history.replaceState({}, '', 'http://localhost:3000/#/create?url=https%3A%2F%2Fexample.com%2Farticles');
-
     render(<App />);
 
     await waitFor(() => {
-      expect(screen.getByLabelText(COPY.urlLabel)).toHaveValue('https://example.com/articles');
+      expect(screen.getByLabelText(COPY.urlLabel)).toHaveValue(EXAMPLE_URL);
     });
   });
 
@@ -1052,96 +798,40 @@ describe('App', () => {
       JSON.stringify({ url: 'https://old.example.com/page' })
     );
     history.replaceState({}, '', 'http://localhost:3000/#/create?url=https%3A%2F%2Fexample.com%2Farticles');
-
     render(<App />);
 
     await waitFor(() => {
-      expect(screen.getByLabelText(COPY.urlLabel)).toHaveValue('https://example.com/articles');
+      expect(screen.getByLabelText(COPY.urlLabel)).toHaveValue(EXAMPLE_URL);
     });
   });
 
   it('shows generic retry action for alternate retry metadata and reruns create', async () => {
-    mockUseFeedCreation.mockReturnValue({
-      isCreating: false,
-      result: undefined,
-      error: {
-        kind: 'server',
-        code: 'INTERNAL_SERVER_ERROR',
-        retryable: true,
-        nextAction: 'retry',
-        retryAction: 'alternate',
-        message: 'Browserless failed.',
-      },
-      createFeed: mockCreateFeed,
-      clearError: mockClearCreationError,
-      clearResult: mockClearResult,
-      retryPreviewFetch: mockRetryPreviewFetch,
-    });
-    mockUseAccessToken.mockReturnValue({
-      token: 'saved-token',
-      hasToken: true,
-      saveToken: mockSaveToken,
-      clearToken: mockClearToken,
-      isLoading: false,
-      error: undefined,
-    });
-
+    stubCreation({ error: serverError('Browserless failed.', 'alternate') });
+    withMemberSession();
     render(<App />);
-
-    fireEvent.input(screen.getByLabelText(COPY.urlLabel), {
-      target: { value: 'https://example.com/articles' },
-    });
+    fillUrl();
     fireEvent.click(screen.getByRole('button', { name: COPY.tryAgain }));
 
     expect(screen.queryByRole('button', { name: /Retry with .*/ })).not.toBeInTheDocument();
-
     await waitFor(() => {
-      expect(mockCreateFeed).toHaveBeenCalledWith('https://example.com/articles', 'saved-token');
+      expect(mockCreateFeed).toHaveBeenCalledWith(EXAMPLE_URL, 'saved-token');
     });
   });
 
   it('shows Try again for primary retry metadata and reruns the create flow', async () => {
-    mockUseFeedCreation.mockReturnValue({
-      isCreating: false,
-      result: undefined,
-      error: {
-        kind: 'server',
-        code: 'INTERNAL_SERVER_ERROR',
-        retryable: true,
-        nextAction: 'retry',
-        retryAction: 'primary',
-        message: 'Browserless failed.',
-      },
-      createFeed: mockCreateFeed,
-      clearError: mockClearCreationError,
-      clearResult: mockClearResult,
-      retryPreviewFetch: mockRetryPreviewFetch,
-    });
-    mockUseAccessToken.mockReturnValue({
-      token: 'saved-token',
-      hasToken: true,
-      saveToken: mockSaveToken,
-      clearToken: mockClearToken,
-      isLoading: false,
-      error: undefined,
-    });
-
+    stubCreation({ error: serverError('Browserless failed.') });
+    withMemberSession();
     render(<App />);
-
-    fireEvent.input(screen.getByLabelText(COPY.urlLabel), {
-      target: { value: 'https://example.com/articles' },
-    });
+    fillUrl();
     fireEvent.click(screen.getByRole('button', { name: COPY.tryAgain }));
 
     await waitFor(() => {
-      expect(mockCreateFeed).toHaveBeenCalledWith('https://example.com/articles', 'saved-token');
+      expect(mockCreateFeed).toHaveBeenCalledWith(EXAMPLE_URL, 'saved-token');
     });
   });
 
   it('does not treat non-token forbidden failures as token rejection', async () => {
-    mockUseFeedCreation.mockReturnValue({
-      isCreating: false,
-      result: undefined,
+    stubCreation({
       error: {
         kind: 'server',
         code: 'FORBIDDEN',
@@ -1150,20 +840,8 @@ describe('App', () => {
         retryAction: 'none',
         message: 'URL not allowed for this account',
       },
-      createFeed: mockCreateFeed,
-      clearError: mockClearCreationError,
-      clearResult: mockClearResult,
-      retryPreviewFetch: mockRetryPreviewFetch,
-    });
-    mockUseAccessToken.mockReturnValue({
-      token: 'saved-token',
-      hasToken: true,
-      saveToken: mockSaveToken,
-      clearToken: mockClearToken,
-      isLoading: false,
-      error: undefined,
     });
-
+    withMemberSession();
     render(<App />);
 
     await screen.findByText('URL not allowed for this account');
@@ -1175,31 +853,18 @@ describe('App', () => {
   });
 
   it('keeps extraction-empty failures generic and input-corrective', async () => {
-    mockUseFeedCreation.mockReturnValue({
-      isCreating: false,
-      result: undefined,
+    stubCreation({
       error: {
         kind: 'input',
         code: 'NO_FEED_ITEMS_EXTRACTED',
         retryable: false,
         nextAction: 'correct_input',
         retryAction: 'none',
-        message: 'Could not extract feed items. Try a more specific listing URL or explicit selectors.',
+        message:
+          'Could not extract feed items. Try a more specific listing URL or explicit selectors.',
       },
-      createFeed: mockCreateFeed,
-      clearError: mockClearCreationError,
-      clearResult: mockClearResult,
-      retryPreviewFetch: mockRetryPreviewFetch,
-    });
-    mockUseAccessToken.mockReturnValue({
-      token: 'saved-token',
-      hasToken: true,
-      saveToken: mockSaveToken,
-      clearToken: mockClearToken,
-      isLoading: false,
-      error: undefined,
     });
-
+    withMemberSession();
     render(<App />);
 
     await screen.findByText(
@@ -1213,22 +878,10 @@ describe('App', () => {
   });
 
   it('returns non-auth token save failures onto create with notice', async () => {
-    mockCreateFeed.mockRejectedValueOnce({
-      kind: 'server',
-      code: 'INTERNAL_SERVER_ERROR',
-      retryable: true,
-      nextAction: 'retry',
-      retryAction: 'primary',
-      message: 'Upstream failed',
-    });
-
+    mockCreateFeed.mockRejectedValueOnce(serverError('Upstream failed'));
     render(<App />);
-
-    fireEvent.input(screen.getByLabelText(COPY.urlLabel), {
-      target: { value: 'https://example.com/articles' },
-    });
-    fireEvent.click(screen.getByRole('button', { name: COPY.createFeed }));
-
+    fillUrl();
+    clickCreate();
     const accessTokenInput = document.querySelector('#access-token') as HTMLInputElement;
     fireEvent.input(accessTokenInput, { target: { value: 'token-123' } });
     fireEvent.click(screen.getByRole('button', { name: COPY.saveAndContinue }));
@@ -1243,11 +896,8 @@ describe('App', () => {
 
   it('cancels the token dialog with Back, Escape, and backdrop', async () => {
     render(<App />);
-
-    fireEvent.input(screen.getByLabelText(COPY.urlLabel), {
-      target: { value: 'https://example.com/articles' },
-    });
-    fireEvent.click(screen.getByRole('button', { name: COPY.createFeed }));
+    fillUrl();
+    clickCreate();
 
     expect(document.querySelector('dialog')).toHaveAttribute('open');
     const accessTokenInput = document.querySelector('#access-token') as HTMLInputElement;
@@ -1259,7 +909,7 @@ describe('App', () => {
     });
     expect(document.querySelector('dialog')).toBeNull();
 
-    fireEvent.click(screen.getByRole('button', { name: COPY.createFeed }));
+    clickCreate();
     const dialog = document.querySelector('dialog');
     expect(dialog).toHaveAttribute('open');
     expect((document.querySelector('#access-token') as HTMLInputElement).value).toBe('');
@@ -1269,7 +919,7 @@ describe('App', () => {
       expect(location.hash).toMatch(/^#\/create/);
     });
 
-    fireEvent.click(screen.getByRole('button', { name: COPY.createFeed }));
+    clickCreate();
     const openDialog = document.querySelector('dialog') as HTMLDialogElement;
     expect(openDialog).toHaveAttribute('open');
     fireEvent.click(openDialog);
@@ -1281,7 +931,6 @@ describe('App', () => {
   });
 
   it('shows the utility links in a user-focused order', () => {
-    history.replaceState({}, '', 'http://localhost:3000/#/create');
     render(<App />);
 
     const utilityLinks = [
@@ -1294,14 +943,13 @@ describe('App', () => {
       COPY.openapiSpec,
       COPY.sourceCode,
     ]);
-
     expect(screen.getByRole('link', { name: COPY.openapiSpec })).toHaveAttribute(
       'href',
       'https://example.test/openapi.yaml'
     );
     expect(screen.getByRole('link', { name: COPY.browseFeedDirectory() })).toHaveAttribute(
       'href',
-      'https://html2rss.github.io/feed-directory/#!url=http%3A%2F%2Flocalhost%3A3000%2F'
+      DIRECTORY_HREF
     );
     expect(screen.getByRole('link', { name: COPY.dockerInstall })).toHaveAttribute(
       'href',
@@ -1310,27 +958,7 @@ describe('App', () => {
   });
 
   it('keeps OpenAPI link on the frontend origin during local development', () => {
-    mockUseApiMetadata.mockReturnValue({
-      metadata: {
-        api: {
-          name: 'html2rss-web API',
-          description: 'RESTful API for converting websites to RSS feeds',
-          openapi_url: 'http://127.0.0.1:4000/openapi.yaml',
-        },
-        instance: {
-          feed_creation: {
-            enabled: true,
-            access_token_required: true,
-          },
-          studio: { enabled: true },
-          catalog: { enabled: true, url: '/api/v1/configs' },
-        },
-      },
-      isLoading: false,
-      error: undefined,
-    });
-
-    history.replaceState({}, '', 'http://localhost:3000/#/create');
+    stubMetadata({ openapiUrl: 'http://127.0.0.1:4000/openapi.yaml' });
     render(<App />);
 
     expect(screen.getByRole('link', { name: COPY.openapiSpec })).toHaveAttribute(
@@ -1338,13 +966,4 @@ describe('App', () => {
       'http://localhost:3000/openapi.yaml'
     );
   });
-
-  it('shows footer utilities on result routes', async () => {
-    history.replaceState({}, '', 'http://localhost:3000/#/result/generated-token');
-    render(<App />);
-
-    await waitFor(() => {
-      expect(screen.getByLabelText(COPY.utilities)).toBeInTheDocument();
-    });
-  });
 });

From 5e47acd12ea1f0b3c39509df6e991c34daef5c85 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 20 Sep 2026 12:14:38 +0200
Subject: [PATCH 052/108] test(frontend): streamline studio timing coverage

Zero out ConfigStudio settle delays via a file-local useStudio wrap,
share Studio response builders, and keep useStudio debounce proofs on
deterministic fake timers without waitFor under those timers.
---
 frontend/src/__tests__/ConfigStudio.test.tsx | 300 ++++++++-----------
 frontend/src/__tests__/useStudio.test.ts     | 261 +++++++---------
 2 files changed, 238 insertions(+), 323 deletions(-)

diff --git a/frontend/src/__tests__/ConfigStudio.test.tsx b/frontend/src/__tests__/ConfigStudio.test.tsx
index eaa9de52..3132e3ce 100644
--- a/frontend/src/__tests__/ConfigStudio.test.tsx
+++ b/frontend/src/__tests__/ConfigStudio.test.tsx
@@ -6,24 +6,110 @@ import { server } from './mocks/server';
 import { ConfigStudio, STUDIO_URL_SETTLE_MS } from '../components/ConfigStudio';
 import { COPY } from '../journey/copy';
 
+vi.mock('../studio/useStudio', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../studio/useStudio')>();
+  return {
+    ...actual,
+    useStudio: (options: Parameters<typeof actual.useStudio>[0]) =>
+      actual.useStudio({ ...options, validateDelayMs: 0, previewSettleMs: 0 }),
+  };
+});
+
 const pageUrl = 'https://example.com/articles';
 
+function suggestEnvelope(selector = 'article', isEnhanced = false, extras: Record<string, unknown> = {}) {
+  return {
+    success: true,
+    data: {
+      selectors: { items: { selector, enhance: isEnhanced } },
+      segment_strategy: 'list',
+      admission_drops: { chrome: 0 },
+      enhance: isEnhanced,
+      ...extras,
+    },
+  };
+}
+
+function validateEnvelope(
+  selectors: unknown = { items: { selector: 'article', enhance: false } },
+  report: { success: boolean; issues: unknown[] } = { success: true, issues: [] }
+) {
+  return {
+    success: true,
+    data: {
+      report,
+      selectors,
+      yaml: 'selectors: {}',
+    },
+  };
+}
+
+function previewEnvelope(
+  items: Array<Record<string, unknown>>,
+  quality: Record<string, unknown> = { warnings: [], metrics: { short_title_count: 0 } }
+) {
+  return {
+    success: true,
+    data: {
+      item_count: items.length,
+      sample_items: items,
+      quality_report: quality,
+      failure_kind: '',
+      validation_issues: [],
+    },
+  };
+}
+
+const previewWithImage = () =>
+  previewEnvelope([
+    {
+      title: 'With image',
+      url: 'https://example.com/sample',
+      published_at: '2024-01-02',
+      image: 'https://cdn.example/a.jpg',
+    },
+    { title: 'No image', url: 'https://example.com/plain' },
+  ]);
+
+function echoValidate() {
+  server.use(
+    http.post('/api/v1/feeds/validate', async ({ request }) => {
+      const body: unknown = await request.json();
+      const selectors =
+        typeof body === 'object' && body && 'selectors' in body
+          ? body.selectors
+          : { items: { selector: 'article', enhance: false } };
+      return HttpResponse.json(validateEnvelope(selectors));
+    })
+  );
+}
+
+function stubSuggest(body: unknown = suggestEnvelope()) {
+  server.use(http.post('/api/v1/feeds/suggest_selectors', () => HttpResponse.json(body)));
+}
+
+function stubPreview(body: unknown) {
+  server.use(http.post('/api/v1/feeds/preview', () => HttpResponse.json(body)));
+}
+
 function renderStudio(
   onGenerate = vi.fn<(selectors: RefinedSelectorsDocument) => Promise<void>>(),
   {
     url = pageUrl,
     onUrlChange = vi.fn(),
     onUrlCleared = vi.fn(),
+    token = 'tok',
   }: {
     url?: string;
     onUrlChange?: (url: string) => void;
     onUrlCleared?: () => void;
+    token?: string;
   } = {}
 ) {
   render(
     <ConfigStudio
       url={url}
-      token="tok"
+      token={token}
       onUrlChange={onUrlChange}
       onUrlCleared={onUrlCleared}
       onGenerate={onGenerate}
@@ -32,55 +118,13 @@ function renderStudio(
   return { onGenerate, onUrlChange, onUrlCleared };
 }
 
-function echoValidate() {
-  server.use(
-    http.post('/api/v1/feeds/validate', async ({ request }) => {
-      const body: unknown = await request.json();
-      const selectors =
-        typeof body === 'object' && body && 'selectors' in body
-          ? body.selectors
-          : { items: { selector: 'article', enhance: false } };
-
-      return HttpResponse.json({
-        success: true,
-        data: {
-          report: { success: true, issues: [] },
-          selectors,
-          yaml: 'selectors: {}',
-        },
-      });
-    })
-  );
-}
-
-function previewWithImage() {
-  return {
-    success: true,
-    data: {
-      item_count: 2,
-      sample_items: [
-        {
-          title: 'With image',
-          url: 'https://example.com/sample',
-          published_at: '2024-01-02',
-          image: 'https://cdn.example/a.jpg',
-        },
-        { title: 'No image', url: 'https://example.com/plain' },
-      ],
-      quality_report: { warnings: [], metrics: { short_title_count: 0 } },
-      failure_kind: '',
-      validation_issues: [],
-    },
-  };
-}
-
 describe('ConfigStudio', () => {
   it('leads with the preview meadow above the items selector when live preview is ready', async () => {
     echoValidate();
-    server.use(http.post('/api/v1/feeds/preview', () => HttpResponse.json(previewWithImage())));
+    stubPreview(previewWithImage());
     renderStudio();
 
-    await waitFor(() => expect(screen.getByText('With image')).toBeInTheDocument(), { timeout: 4000 });
+    await waitFor(() => expect(screen.getByText('With image')).toBeInTheDocument());
 
     const meadow = screen.getByLabelText(COPY.previewRegion);
     const items = screen.getByLabelText(COPY.itemsSelector);
@@ -120,15 +164,7 @@ describe('ConfigStudio', () => {
     server.use(
       http.post('/api/v1/feeds/suggest_selectors', async ({ request }) => {
         suggestBodies.push(await request.json());
-        return HttpResponse.json({
-          success: true,
-          data: {
-            selectors: { items: { selector: 'article', enhance: false } },
-            segment_strategy: 'list',
-            admission_drops: {},
-            enhance: false,
-          },
-        });
+        return HttpResponse.json(suggestEnvelope());
       })
     );
 
@@ -159,23 +195,12 @@ describe('ConfigStudio', () => {
     echoValidate();
     const pendingSuggestion = Promise.withResolvers<Response>();
     server.use(http.post('/api/v1/feeds/suggest_selectors', () => pendingSuggestion.promise));
-
     renderStudio();
 
     const items = screen.getByLabelText(COPY.itemsSelector);
     expect(items).toHaveValue('a[href]');
 
-    pendingSuggestion.resolve(
-      HttpResponse.json({
-        success: true,
-        data: {
-          selectors: { items: { selector: '.post', enhance: true } },
-          segment_strategy: 'list',
-          admission_drops: { chrome: 0 },
-          enhance: true,
-        },
-      })
-    );
+    pendingSuggestion.resolve(HttpResponse.json(suggestEnvelope('.post', true)));
 
     await waitFor(() => expect(items).toHaveValue('.post'));
     expect(screen.getByLabelText(COPY.enhanceItems)).toBeChecked();
@@ -183,20 +208,7 @@ describe('ConfigStudio', () => {
 
   it('checks enhance from suggestion and prefills an empty items selector', async () => {
     echoValidate();
-    server.use(
-      http.post('/api/v1/feeds/suggest_selectors', () =>
-        HttpResponse.json({
-          success: true,
-          data: {
-            selectors: { items: { selector: '.post', enhance: true } },
-            segment_strategy: 'list',
-            admission_drops: { chrome: 2 },
-            enhance: true,
-          },
-        })
-      )
-    );
-
+    stubSuggest(suggestEnvelope('.post', true, { admission_drops: { chrome: 2 } }));
     renderStudio();
 
     await waitFor(() => expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('.post'));
@@ -211,20 +223,9 @@ describe('ConfigStudio', () => {
     echoValidate();
     const pendingSuggestion = Promise.withResolvers<Response>();
     server.use(http.post('/api/v1/feeds/suggest_selectors', () => pendingSuggestion.promise));
-
     renderStudio();
     fireEvent.input(screen.getByLabelText(COPY.itemsSelector), { target: { value: 'article.mine' } });
-    pendingSuggestion.resolve(
-      HttpResponse.json({
-        success: true,
-        data: {
-          selectors: { items: { selector: '.post', enhance: true } },
-          segment_strategy: 'list',
-          admission_drops: { chrome: 0 },
-          enhance: true,
-        },
-      })
-    );
+    pendingSuggestion.resolve(HttpResponse.json(suggestEnvelope('.post', true)));
 
     await waitFor(() => expect(screen.getByLabelText(COPY.enhanceItems)).toBeChecked());
     expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('article.mine');
@@ -232,20 +233,7 @@ describe('ConfigStudio', () => {
 
   it('applies the capture suggestion in one click', async () => {
     echoValidate();
-    server.use(
-      http.post('/api/v1/feeds/suggest_selectors', () =>
-        HttpResponse.json({
-          success: true,
-          data: {
-            selectors: { items: { selector: '.post', enhance: true } },
-            segment_strategy: 'list',
-            admission_drops: { chrome: 2 },
-            enhance: true,
-          },
-        })
-      )
-    );
-
+    stubSuggest(suggestEnvelope('.post', true, { admission_drops: { chrome: 2 } }));
     renderStudio();
     fireEvent.click(screen.getByRole('button', { name: COPY.applySuggestion }));
 
@@ -257,28 +245,23 @@ describe('ConfigStudio', () => {
   it('opens a fix-a-field selector panel without cleanup controls', async () => {
     server.use(
       http.post('/api/v1/feeds/validate', () =>
-        HttpResponse.json({
-          success: true,
-          data: {
-            report: {
-              success: false,
-              issues: [
-                {
-                  path: ['selectors', 'title', 'selector'],
-                  code: 'missing_key',
-                  message: 'is missing',
-                },
-                {
-                  path: ['selectors', 'url', 'selector'],
-                  code: 'constraint',
-                  message: 'is invalid',
-                },
-              ],
-            },
-            selectors: { items: { selector: 'article', enhance: false } },
-            yaml: 'selectors: {}',
-          },
-        })
+        HttpResponse.json(
+          validateEnvelope({ items: { selector: 'article', enhance: false } }, {
+            success: false,
+            issues: [
+              {
+                path: ['selectors', 'title', 'selector'],
+                code: 'missing_key',
+                message: 'is missing',
+              },
+              {
+                path: ['selectors', 'url', 'selector'],
+                code: 'constraint',
+                message: 'is invalid',
+              },
+            ],
+          })
+        )
       )
     );
 
@@ -297,35 +280,27 @@ describe('ConfigStudio', () => {
 
   it('auto-fetches a preview with url and date after validation', async () => {
     echoValidate();
-    server.use(
-      http.post('/api/v1/feeds/preview', () =>
-        HttpResponse.json({
-          success: true,
-          data: {
-            item_count: 1,
-            sample_items: [
-              {
-                title: 'Sample headline',
-                url: 'https://example.com/sample',
-                published_at: '2024-01-02',
-              },
-            ],
-            quality_report: {
-              warnings: ['native_feed_present'],
-              metrics: { short_title_count: 0 },
-              native_feed: 'https://example.com/feed.xml',
-            },
-            failure_kind: '',
-            validation_issues: [],
+    stubPreview(
+      previewEnvelope(
+        [
+          {
+            title: 'Sample headline',
+            url: 'https://example.com/sample',
+            published_at: '2024-01-02',
           },
-        })
+        ],
+        {
+          warnings: ['native_feed_present'],
+          metrics: { short_title_count: 0 },
+          native_feed: 'https://example.com/feed.xml',
+        }
       )
     );
 
     renderStudio();
 
     expect(screen.queryByRole('button', { name: COPY.previewChecking })).not.toBeInTheDocument();
-    await waitFor(() => expect(screen.getByText('Sample headline')).toBeInTheDocument(), { timeout: 4000 });
+    await waitFor(() => expect(screen.getByText('Sample headline')).toBeInTheDocument());
     expect(screen.getByRole('link', { name: 'Sample headline' })).toHaveAttribute(
       'href',
       'https://example.com/sample'
@@ -346,11 +321,10 @@ describe('ConfigStudio', () => {
 
   it('renders a sample image only for an authenticated session when a url exists', async () => {
     echoValidate();
-    server.use(http.post('/api/v1/feeds/preview', () => HttpResponse.json(previewWithImage())));
-
+    stubPreview(previewWithImage());
     renderStudio();
 
-    await waitFor(() => expect(screen.getByText('With image')).toBeInTheDocument(), { timeout: 4000 });
+    await waitFor(() => expect(screen.getByText('With image')).toBeInTheDocument());
     const images = document.querySelectorAll('img.refine-sample-image');
     expect(images).toHaveLength(1);
     const image = images[0];
@@ -365,31 +339,19 @@ describe('ConfigStudio', () => {
 
   it('does not request a sample image without an access token', async () => {
     echoValidate();
-    server.use(http.post('/api/v1/feeds/preview', () => HttpResponse.json(previewWithImage())));
-
-    render(
-      <ConfigStudio
-        url={pageUrl}
-        token="  "
-        onUrlChange={vi.fn()}
-        onUrlCleared={vi.fn()}
-        onGenerate={vi.fn()}
-      />
-    );
+    stubPreview(previewWithImage());
+    renderStudio(vi.fn(), { token: '  ' });
 
-    await waitFor(() => expect(screen.getByText('With image')).toBeInTheDocument(), { timeout: 4000 });
+    await waitFor(() => expect(screen.getByText('With image')).toBeInTheDocument());
     expect(document.querySelector('img')).toBeNull();
   });
 
   it('offers check again when the live preview cannot be fetched', async () => {
     echoValidate();
     server.use(http.post('/api/v1/feeds/preview', () => HttpResponse.error()));
-
     renderStudio();
 
-    expect(
-      await screen.findByRole('button', { name: COPY.checkAgain }, { timeout: 4000 })
-    ).toBeInTheDocument();
+    expect(await screen.findByRole('button', { name: COPY.checkAgain })).toBeInTheDocument();
     expect(screen.getByText(COPY.previewFetchedCaption)).toBeInTheDocument();
   });
 
diff --git a/frontend/src/__tests__/useStudio.test.ts b/frontend/src/__tests__/useStudio.test.ts
index a633370e..2095afee 100644
--- a/frontend/src/__tests__/useStudio.test.ts
+++ b/frontend/src/__tests__/useStudio.test.ts
@@ -53,6 +53,20 @@ function suggestionBody(isEnhanced = false, selector = 'article') {
   };
 }
 
+function previewBody(sampleItems: unknown[], extras: Record<string, unknown> = {}) {
+  return {
+    success: true,
+    data: {
+      item_count: sampleItems.length,
+      sample_items: sampleItems,
+      quality_report: { warnings: [], metrics: { short_title_count: 0 } },
+      failure_kind: wireNull,
+      validation_issues: [],
+      ...extras,
+    },
+  };
+}
+
 function callsTo(fetchMock: SpyInstance, suffix: string) {
   return fetchMock.mock.calls.filter((call) => {
     const input = call[0];
@@ -61,6 +75,45 @@ function callsTo(fetchMock: SpyInstance, suffix: string) {
   });
 }
 
+async function advanceValidate(ms = STUDIO_VALIDATE_DELAY_MS) {
+  await act(async () => {
+    await vi.advanceTimersByTimeAsync(ms);
+  });
+}
+
+async function advancePreview(ms = STUDIO_PREVIEW_SETTLE_MS) {
+  await act(async () => {
+    await vi.advanceTimersByTimeAsync(ms);
+  });
+}
+
+function mockStudioFetch(
+  fetchMock: SpyInstance,
+  handlers: {
+    suggest?: () => Promise<Response> | Response;
+    preview?: () => Promise<Response> | Response;
+    validate?: (selectors: unknown) => Promise<Response> | Response;
+  } = {}
+) {
+  fetchMock.mockImplementation(async (input: RequestInfo | URL, init?: RequestInit) => {
+    const path = fetchPath(input);
+    if (path.endsWith('/feeds/suggest_selectors')) {
+      return handlers.suggest?.() ?? Response.json(suggestionBody(false));
+    }
+    if (path.endsWith('/feeds/preview')) {
+      return handlers.preview?.() ?? Response.json(previewBody([]));
+    }
+    const parsed = await fetchJsonBody(input, init);
+    const selectors = selectorsFromBody(parsed);
+    if (handlers.validate) return handlers.validate(selectors);
+    return Response.json(
+      validateBody({
+        selectors: selectors ?? { items: { selector: 'article', enhance: false } },
+      })
+    );
+  });
+}
+
 describe('selector draft', () => {
   it('starts the items selector at the gem default a[href]', () => {
     expect(emptyDraft().itemsSelector).toBe('a[href]');
@@ -125,12 +178,7 @@ describe('useStudio', () => {
 
   it('waits 300ms, sends the bearer token, and unwraps a valid report', async () => {
     vi.useFakeTimers();
-    fetchMock.mockImplementation((input: RequestInfo | URL) => {
-      if (fetchPath(input).endsWith('/feeds/suggest_selectors')) {
-        return Promise.resolve(Response.json(suggestionBody(false)));
-      }
-      return Promise.resolve(Response.json(validateBody()));
-    });
+    mockStudioFetch(fetchMock);
 
     const { result } = renderHook(() => useStudio({ url: pageUrl, token }));
     expect(callsTo(fetchMock, '/feeds/validate')).toHaveLength(0);
@@ -141,14 +189,10 @@ describe('useStudio', () => {
     expect(result.current.state.draft.itemsSelector).toBe('article');
     expect(callsTo(fetchMock, '/feeds/validate')).toHaveLength(0);
 
-    await act(async () => {
-      await vi.advanceTimersByTimeAsync(STUDIO_VALIDATE_DELAY_MS - 1);
-    });
+    await advanceValidate(STUDIO_VALIDATE_DELAY_MS - 1);
     expect(callsTo(fetchMock, '/feeds/validate')).toHaveLength(0);
 
-    await act(async () => {
-      await vi.advanceTimersByTimeAsync(1);
-    });
+    await advanceValidate(1);
 
     const validateCalls = callsTo(fetchMock, '/feeds/validate');
     expect(validateCalls).toHaveLength(1);
@@ -172,11 +216,8 @@ describe('useStudio', () => {
 
   it('keeps returned issue codes on the invalid phase and does not preview', async () => {
     vi.useFakeTimers();
-    fetchMock.mockImplementation((input: RequestInfo | URL) => {
-      if (fetchPath(input).endsWith('/feeds/suggest_selectors')) {
-        return Promise.resolve(Response.json(suggestionBody(false)));
-      }
-      return Promise.resolve(
+    mockStudioFetch(fetchMock, {
+      validate: () =>
         Response.json(
           validateBody({
             report: {
@@ -192,15 +233,17 @@ describe('useStudio', () => {
             selectors: { items: { enhance: false } },
             yaml: wireNull,
           })
-        )
-      );
+        ),
     });
 
     const { result } = renderHook(() => useStudio({ url: pageUrl, token, validateDelayMs: 0 }));
     await act(async () => {
       await vi.advanceTimersByTimeAsync(0);
     });
-    await waitFor(() => expect(result.current.state.phase).toBe('invalid'));
+    await act(async () => {
+      await Promise.resolve();
+    });
+    expect(result.current.state.phase).toBe('invalid');
 
     const state = result.current.state;
     if (state.phase !== 'invalid') return;
@@ -212,40 +255,26 @@ describe('useStudio', () => {
       },
     ]);
 
-    await act(async () => {
-      await vi.advanceTimersByTimeAsync(STUDIO_PREVIEW_SETTLE_MS);
-    });
+    await advancePreview();
     expect(callsTo(fetchMock, '/feeds/preview')).toHaveLength(0);
   });
 
   it('previews only after validation succeeds and the settle delay', async () => {
     vi.useFakeTimers();
-    fetchMock.mockImplementation((input: RequestInfo | URL) => {
-      const path = fetchPath(input);
-      if (path.endsWith('/feeds/suggest_selectors')) {
-        return Promise.resolve(Response.json(suggestionBody(false)));
-      }
-      if (path.endsWith('/feeds/preview')) {
-        return Promise.resolve(
-          Response.json({
-            success: true,
-            data: {
-              item_count: 1,
-              sample_items: [
-                { title: 'Sample', url: 'https://example.com/sample', published_at: '2024-01-02' },
-              ],
+    mockStudioFetch(fetchMock, {
+      preview: () =>
+        Response.json(
+          previewBody(
+            [{ title: 'Sample', url: 'https://example.com/sample', published_at: '2024-01-02' }],
+            {
               quality_report: {
                 warnings: [],
                 metrics: { short_title_count: 0 },
                 native_feed: 'https://example.com/feed.xml',
               },
-              failure_kind: wireNull,
-              validation_issues: [],
-            },
-          })
-        );
-      }
-      return Promise.resolve(Response.json(validateBody()));
+            }
+          )
+        ),
     });
 
     const { result } = renderHook(() =>
@@ -257,19 +286,13 @@ describe('useStudio', () => {
     });
     expect(result.current.state.draft.itemsSelector).toBe('article');
 
-    await act(async () => {
-      await vi.advanceTimersByTimeAsync(STUDIO_VALIDATE_DELAY_MS);
-    });
+    await advanceValidate();
     expect(callsTo(fetchMock, '/feeds/preview')).toHaveLength(0);
 
-    await act(async () => {
-      await vi.advanceTimersByTimeAsync(STUDIO_PREVIEW_SETTLE_MS - 1);
-    });
+    await advancePreview(STUDIO_PREVIEW_SETTLE_MS - 1);
     expect(callsTo(fetchMock, '/feeds/preview')).toHaveLength(0);
 
-    await act(async () => {
-      await vi.advanceTimersByTimeAsync(1);
-    });
+    await advancePreview(1);
 
     const state = result.current.state;
     expect(state.live.status).toBe('ready');
@@ -292,31 +315,15 @@ describe('useStudio', () => {
 
   it('starts at a[href], auto-suggests with an empty hint, then applies the determined selector', async () => {
     const pendingSuggestion = Promise.withResolvers<Response>();
-    fetchMock.mockImplementation(async (input: RequestInfo | URL, init?: RequestInit) => {
-      if (fetchPath(input).endsWith('/feeds/suggest_selectors')) {
-        return pendingSuggestion.promise;
-      }
-      if (fetchPath(input).endsWith('/feeds/preview')) {
-        return Response.json({
-          success: true,
-          data: {
-            item_count: 0,
-            sample_items: [],
-            quality_report: { warnings: [], metrics: { short_title_count: 0 } },
-            failure_kind: wireNull,
-            validation_issues: [],
-          },
-        });
-      }
-
-      const parsed = await fetchJsonBody(input, init);
-      const selectors = selectorsFromBody(parsed);
-      return Response.json(
-        validateBody({
-          selectors: selectors ?? { items: { selector: 'a[href]', enhance: false } },
-          yaml: 'selectors: {}\n',
-        })
-      );
+    mockStudioFetch(fetchMock, {
+      suggest: () => pendingSuggestion.promise,
+      validate: (selectors) =>
+        Response.json(
+          validateBody({
+            selectors: selectors ?? { items: { selector: 'a[href]', enhance: false } },
+            yaml: 'selectors: {}\n',
+          })
+        ),
     });
 
     const { result } = renderHook(() =>
@@ -345,30 +352,9 @@ describe('useStudio', () => {
 
   it('does not overwrite an items selector the user already typed', async () => {
     const pendingSuggestion = Promise.withResolvers<Response>();
-    fetchMock.mockImplementation(async (input: RequestInfo | URL, init?: RequestInit) => {
-      if (fetchPath(input).endsWith('/feeds/suggest_selectors')) {
-        return pendingSuggestion.promise;
-      }
-      if (fetchPath(input).endsWith('/feeds/preview')) {
-        return Response.json({
-          success: true,
-          data: {
-            item_count: 0,
-            sample_items: [],
-            quality_report: wireNull,
-            failure_kind: wireNull,
-            validation_issues: [],
-          },
-        });
-      }
-
-      const parsed = await fetchJsonBody(input, init);
-      const selectors = selectorsFromBody(parsed);
-      return Response.json(
-        validateBody({
-          selectors: selectors ?? { items: { selector: 'article', enhance: false } },
-        })
-      );
+    mockStudioFetch(fetchMock, {
+      suggest: () => pendingSuggestion.promise,
+      preview: () => Response.json(previewBody([], { quality_report: wireNull })),
     });
 
     const { result } = renderHook(() =>
@@ -389,34 +375,22 @@ describe('useStudio', () => {
   });
 
   it('keeps an http image url from the preview sample and drops anything else', async () => {
-    fetchMock.mockImplementation((input: RequestInfo | URL) => {
-      const path = fetchPath(input);
-      if (path.endsWith('/feeds/suggest_selectors')) {
-        return Promise.resolve(Response.json(suggestionBody(false)));
-      }
-      if (path.endsWith('/feeds/preview')) {
-        return Promise.resolve(
-          Response.json({
-            success: true,
-            data: {
-              item_count: 2,
-              sample_items: [
-                {
-                  title: 'With image',
-                  url: 'https://example.com/a',
-                  published_at: '2024-01-02',
-                  image: 'https://cdn.example/a.jpg',
-                },
-                { title: 'Unsafe image', image: 'javascript:alert(1)' },
-              ],
-              quality_report: wireNull,
-              failure_kind: wireNull,
-              validation_issues: [],
-            },
-          })
-        );
-      }
-      return Promise.resolve(Response.json(validateBody()));
+    mockStudioFetch(fetchMock, {
+      preview: () =>
+        Response.json(
+          previewBody(
+            [
+              {
+                title: 'With image',
+                url: 'https://example.com/a',
+                published_at: '2024-01-02',
+                image: 'https://cdn.example/a.jpg',
+              },
+              { title: 'Unsafe image', image: 'javascript:alert(1)' },
+            ],
+            { quality_report: wireNull }
+          )
+        ),
     });
 
     const { result } = renderHook(() =>
@@ -431,30 +405,9 @@ describe('useStudio', () => {
   });
 
   it('applies one capture suggestion onto the items selector', async () => {
-    fetchMock.mockImplementation(async (input: RequestInfo | URL, init?: RequestInit) => {
-      if (fetchPath(input).endsWith('/feeds/suggest_selectors')) {
-        return Response.json(suggestionBody(true, '.post'));
-      }
-      if (fetchPath(input).endsWith('/feeds/preview')) {
-        return Response.json({
-          success: true,
-          data: {
-            item_count: 0,
-            sample_items: [],
-            quality_report: wireNull,
-            failure_kind: wireNull,
-            validation_issues: [],
-          },
-        });
-      }
-
-      const parsed = await fetchJsonBody(input, init);
-      const selectors = selectorsFromBody(parsed);
-      return Response.json(
-        validateBody({
-          selectors: selectors ?? { items: { selector: 'article', enhance: false } },
-        })
-      );
+    mockStudioFetch(fetchMock, {
+      suggest: () => Response.json(suggestionBody(true, '.post')),
+      preview: () => Response.json(previewBody([], { quality_report: wireNull })),
     });
 
     const { result } = renderHook(() =>

From 263dcc651ad5ddc97b2a0f49329103312f1d8778 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 20 Sep 2026 12:15:55 +0200
Subject: [PATCH 053/108] test(frontend): share fixtures across smoke layers

Extract pure API wire builders for MSW and Playwright, then cover
refine URL re-suggest/preview plus empty-blur remount and studio-off
hide/bounce as two deterministic browser journeys.
---
 frontend/e2e/smoke.spec.ts                  | 228 ++++++++++----------
 frontend/src/__tests__/mocks/apiFixtures.ts | 165 ++++++++++++++
 frontend/src/__tests__/mocks/server.ts      | 131 +++--------
 3 files changed, 304 insertions(+), 220 deletions(-)
 create mode 100644 frontend/src/__tests__/mocks/apiFixtures.ts

diff --git a/frontend/e2e/smoke.spec.ts b/frontend/e2e/smoke.spec.ts
index d58fe558..cf9e4aba 100644
--- a/frontend/e2e/smoke.spec.ts
+++ b/frontend/e2e/smoke.spec.ts
@@ -1,5 +1,15 @@
-import { expect, test, type Page } from '@playwright/test';
+import { expect, test, type Page, type Request } from '@playwright/test';
 import { COPY } from '../src/journey/copy';
+import {
+  createdFeedBody,
+  emptyCatalog,
+  jsonPreviewItems,
+  metadataBody,
+  studioPreviewSuccessBody,
+  suggestSuccessBody,
+  validateSuccessBody,
+  type MetadataOptions,
+} from '../src/__tests__/mocks/apiFixtures';
 
 const API_ROOT = /\/api\/v1\/?$/;
 const API_CONFIGS = /\/api\/v1\/configs\/?$/;
@@ -9,45 +19,8 @@ const API_SUGGEST = /\/api\/v1\/feeds\/suggest_selectors\/?$/;
 const API_STUDIO_PREVIEW = /\/api\/v1\/feeds\/preview\/?$/;
 const API_JSON_PREVIEW = /\/api\/v1\/feeds\/generated-token\.json$/;
 
-function metadataBody(isTokenRequired = true, isCatalogEnabled = true) {
-  return {
-    success: true,
-    data: {
-      api: {
-        name: 'html2rss-web API',
-        description: 'RESTful API for converting websites to RSS feeds',
-        openapi_url: 'https://example.test/openapi.yaml',
-      },
-      instance: {
-        feed_creation: { enabled: true, access_token_required: isTokenRequired },
-        studio: { enabled: true },
-        catalog: { enabled: isCatalogEnabled, url: 'https://api.html2rss.dev/api/v1/configs' },
-      },
-    },
-  };
-}
-
-const emptyCatalog = {
-  success: true,
-  data: { configs: [] },
-  meta: { total: 0, catalog_version: 2, starters: [] },
-};
-
-const createdFeed = {
-  success: true,
-  data: {
-    feed: {
-      id: 'feed-123',
-      name: 'Example Feed',
-      url: 'https://example.com/articles',
-      feed_token: 'generated-token',
-      public_url: '/api/v1/feeds/generated-token',
-      json_public_url: '/api/v1/feeds/generated-token.json',
-      created_at: '2026-04-05T08:59:00.000Z',
-      updated_at: '2026-04-05T09:00:00.000Z',
-    },
-  },
-};
+const EXAMPLE_URL = 'https://example.com/articles';
+const BLOG_URL = 'https://example.com/blog';
 
 async function fulfillJson(
   page: Page,
@@ -65,12 +38,9 @@ async function fulfillJson(
   });
 }
 
-async function stubSpaApi(
-  page: Page,
-  options: { isTokenRequired?: boolean; isCatalogEnabled?: boolean } = {}
-) {
+async function stubSpaApi(page: Page, options: MetadataOptions = {}) {
   const isCatalogEnabled = options.isCatalogEnabled ?? true;
-  await fulfillJson(page, API_ROOT, metadataBody(options.isTokenRequired ?? true, isCatalogEnabled));
+  await fulfillJson(page, API_ROOT, metadataBody(options));
   if (isCatalogEnabled) await fulfillJson(page, API_CONFIGS, emptyCatalog);
 }
 
@@ -79,6 +49,40 @@ function isSameOriginApi(url: string, path: RegExp): boolean {
   return path.test(requested.pathname) && requested.host !== 'api.html2rss.dev';
 }
 
+async function stubStudioEndpoints(page: Page) {
+  await fulfillJson(page, API_VALIDATE, validateSuccessBody({ items: { selector: 'article' } }));
+  await fulfillJson(page, API_SUGGEST, suggestSuccessBody('article', false));
+  await fulfillJson(page, API_STUDIO_PREVIEW, studioPreviewSuccessBody());
+}
+
+async function createReadyResult(page: Page, options: MetadataOptions = {}) {
+  await stubSpaApi(page, { isCatalogEnabled: false, ...options });
+  await fulfillJson(page, API_FEEDS, createdFeedBody(), 201);
+  await fulfillJson(page, API_JSON_PREVIEW, { items: [] }, 200, 'application/feed+json');
+  await page.addInitScript(() => {
+    localStorage.setItem('html2rss_access_token', 'token-123');
+  });
+  await page.goto('/');
+  await page.getByLabel(COPY.urlLabel).fill(EXAMPLE_URL);
+  await page.getByRole('button', { name: COPY.createFeed }).click();
+  await expect(page.getByText(COPY.feedReady)).toBeVisible();
+}
+
+async function openRefineFromResult(page: Page) {
+  await stubStudioEndpoints(page);
+  await page.getByRole('button', { name: COPY.refineSelectors }).click();
+  await expect(page).toHaveURL(/\/#\/refine$/);
+  await expect(page.locator('.result-shell[data-state="refine"]')).toBeVisible();
+}
+
+function collectPosts(page: Page, path: RegExp, bag: Request[]) {
+  page.on('request', (request) => {
+    if (request.method() === 'POST' && isSameOriginApi(request.url(), path)) {
+      bag.push(request);
+    }
+  });
+}
+
 test.describe('frontend smoke', () => {
   test('loads create flow and inline access-token gate', async ({ page }) => {
     const catalogUrls: string[] = [];
@@ -94,7 +98,7 @@ test.describe('frontend smoke', () => {
     expect(catalogUrls.length).toBeGreaterThan(0);
     expect(catalogUrls.every((url) => isSameOriginApi(url, API_CONFIGS))).toBe(true);
 
-    await page.getByLabel(COPY.urlLabel).fill('https://example.com/articles');
+    await page.getByLabel(COPY.urlLabel).fill(EXAMPLE_URL);
     await page.getByRole('button', { name: COPY.createFeed }).click();
 
     await expect(page.getByRole('heading', { name: COPY.tokenTitle })).toBeVisible();
@@ -134,7 +138,7 @@ test.describe('frontend smoke', () => {
 
     await page.goto('/#/create');
 
-    await page.getByLabel(COPY.urlLabel).fill('https://example.com/articles');
+    await page.getByLabel(COPY.urlLabel).fill(EXAMPLE_URL);
     await page.getByRole('button', { name: COPY.createFeed }).click();
     await expect(page.getByText(COPY.createFailedRetryTitle, { exact: true })).toBeVisible();
 
@@ -159,30 +163,15 @@ test.describe('frontend smoke', () => {
     page,
   }) => {
     await stubSpaApi(page);
-    await fulfillJson(page, API_FEEDS, createdFeed, 201);
-    await fulfillJson(
-      page,
-      API_JSON_PREVIEW,
-      {
-        items: [
-          {
-            title: 'Sample preview item',
-            content_text: 'Current preview fetch includes rendered content.',
-            date_published: '2026-04-05T09:00:00.000Z',
-            url: 'https://example.com/articles/sample-preview-item',
-          },
-        ],
-      },
-      200,
-      'application/feed+json'
-    );
+    await fulfillJson(page, API_FEEDS, createdFeedBody(), 201);
+    await fulfillJson(page, API_JSON_PREVIEW, jsonPreviewItems, 200, 'application/feed+json');
 
     await page.addInitScript(() => {
       localStorage.setItem('html2rss_access_token', 'token-123');
     });
 
     await page.goto('/');
-    await page.getByLabel(COPY.urlLabel).fill('https://example.com/articles');
+    await page.getByLabel(COPY.urlLabel).fill(EXAMPLE_URL);
 
     const created = page.waitForRequest((request) => {
       if (request.method() !== 'POST' || !isSameOriginApi(request.url(), API_FEEDS)) return false;
@@ -221,55 +210,9 @@ test.describe('frontend smoke', () => {
   });
 
   test('refines a result and generates the feed without a live scrape', async ({ page }) => {
-    await stubSpaApi(page, { isCatalogEnabled: false });
-    await fulfillJson(page, API_FEEDS, createdFeed, 201);
-    await fulfillJson(page, API_JSON_PREVIEW, { items: [] }, 200, 'application/feed+json');
-    await fulfillJson(page, API_VALIDATE, {
-      success: true,
-      data: {
-        report: { success: true, issues: [] },
-        selectors: { items: { selector: 'article' } },
-        yaml: 'selectors:\n  items:\n    selector: article\n',
-      },
-    });
-    await fulfillJson(page, API_SUGGEST, {
-      success: true,
-      data: {
-        selectors: { items: { selector: 'article' } },
-        segment_strategy: 'list',
-        admission_drops: { chrome: 0 },
-        enhance: false,
-      },
-    });
-    await fulfillJson(page, API_STUDIO_PREVIEW, {
-      success: true,
-      data: {
-        item_count: 1,
-        sample_items: [
-          {
-            title: 'Refine meadow item',
-            url: 'https://example.com/refine-item',
-            published_at: '2024-01-02',
-          },
-        ],
-        quality_report: { warnings: [], metrics: { short_title_count: 0 } },
-        failure_kind: '',
-        validation_issues: [],
-      },
-    });
-
-    await page.addInitScript(() => {
-      localStorage.setItem('html2rss_access_token', 'token-123');
-    });
-
-    await page.goto('/');
-    await page.getByLabel(COPY.urlLabel).fill('https://example.com/articles');
-    await page.getByRole('button', { name: COPY.createFeed }).click();
-    await expect(page.getByText(COPY.feedReady)).toBeVisible();
+    await createReadyResult(page);
+    await openRefineFromResult(page);
 
-    await page.getByRole('button', { name: COPY.refineSelectors }).click();
-    await expect(page).toHaveURL(/\/#\/refine$/);
-    await expect(page.locator('.result-shell[data-state="refine"]')).toBeVisible();
     await expect(page.locator('.ui-card')).toHaveCount(0);
     await expect(page.getByText('Refine meadow item')).toBeVisible();
     const meadow = page.getByLabel(COPY.previewRegion, { exact: true });
@@ -296,4 +239,63 @@ test.describe('frontend smoke', () => {
     await expect(page.getByText(COPY.feedReady)).toBeVisible();
     await expect(page).toHaveURL(/\/#\/result\/generated-token$/);
   });
+
+  test('re-suggests and re-previews after refine URL edit then remounts create on empty blur', async ({
+    page,
+  }) => {
+    const suggestRequests: Request[] = [];
+    const previewRequests: Request[] = [];
+    collectPosts(page, API_SUGGEST, suggestRequests);
+    collectPosts(page, API_STUDIO_PREVIEW, previewRequests);
+
+    await createReadyResult(page);
+    await openRefineFromResult(page);
+    await expect(page.getByText('Refine meadow item')).toBeVisible();
+
+    const suggestBeforeEdit = suggestRequests.length;
+    const previewBeforeEdit = previewRequests.length;
+
+    const urlField = page.getByLabel(COPY.urlLabel);
+    await urlField.fill(BLOG_URL);
+    await expect
+      .poll(() => suggestRequests.length, { timeout: 5000 })
+      .toBeGreaterThan(suggestBeforeEdit);
+    await expect
+      .poll(() => previewRequests.length, { timeout: 5000 })
+      .toBeGreaterThan(previewBeforeEdit);
+
+    const latestSuggest = suggestRequests.at(-1);
+    expect(latestSuggest).toBeDefined();
+    expect(latestSuggest?.postDataJSON()).toMatchObject({ url: BLOG_URL });
+
+    await expect(page).toHaveURL(/\/#\/refine$/);
+    await expect(page.locator('.result-shell[data-state="refine"]')).toBeVisible();
+    await expect(page.getByRole('button', { name: COPY.saveAndGenerate })).toHaveCount(1);
+
+    await urlField.fill('   ');
+    await urlField.blur();
+
+    await expect(page).toHaveURL(/\/#\/create$/);
+    await expect(page.locator('.form-shell')).toHaveAttribute('data-state', 'create');
+    await expect(page.getByLabel(COPY.urlLabel)).toBeVisible();
+    await expect(page.getByRole('heading', { name: COPY.refineSelectors })).toHaveCount(0);
+    await expect(page.getByRole('button', { name: COPY.createFeed })).toBeVisible();
+  });
+
+  test('hides refine when studio is disabled and bounces forced refine onto create', async ({
+    page,
+  }) => {
+    await createReadyResult(page, { isStudioEnabled: false });
+
+    await expect(page.getByText(COPY.feedReady)).toBeVisible();
+    await expect(page.getByRole('button', { name: COPY.refineSelectors })).toHaveCount(0);
+    await expect(page.getByRole('button', { name: COPY.createAnother })).toBeVisible();
+
+    await page.goto('/#/refine');
+
+    await expect(page).toHaveURL(/\/#\/create$/);
+    await expect(page.getByLabel(COPY.urlLabel)).toBeVisible();
+    await expect(page.getByRole('heading', { name: COPY.refineSelectors })).toHaveCount(0);
+    await expect(page.locator('.form-shell')).toHaveAttribute('data-state', 'create');
+  });
 });
diff --git a/frontend/src/__tests__/mocks/apiFixtures.ts b/frontend/src/__tests__/mocks/apiFixtures.ts
new file mode 100644
index 00000000..e7fe1e14
--- /dev/null
+++ b/frontend/src/__tests__/mocks/apiFixtures.ts
@@ -0,0 +1,165 @@
+/** Pure API wire fixtures shared by MSW and Playwright. Transport registration stays in each owning layer. */
+
+export type MetadataOptions = {
+  isTokenRequired?: boolean;
+  isCatalogEnabled?: boolean;
+  isStudioEnabled?: boolean;
+  openapiUrl?: string;
+};
+
+export function metadataBody({
+  isTokenRequired = true,
+  isCatalogEnabled = true,
+  isStudioEnabled = true,
+  openapiUrl = 'https://example.test/openapi.yaml',
+}: MetadataOptions = {}) {
+  return {
+    success: true,
+    data: {
+      api: {
+        name: 'html2rss-web API',
+        description: 'RESTful API for converting websites to RSS feeds',
+        openapi_url: openapiUrl,
+      },
+      instance: {
+        feed_creation: { enabled: true, access_token_required: isTokenRequired },
+        studio: { enabled: isStudioEnabled },
+        catalog: {
+          enabled: isCatalogEnabled,
+          url: 'https://api.html2rss.dev/api/v1/configs',
+        },
+      },
+    },
+  };
+}
+
+export const emptyCatalog = {
+  success: true,
+  data: { configs: [] },
+  meta: { total: 0, catalog_version: 2, starters: [] },
+};
+
+export type CreatedFeedOverrides = {
+  id?: string;
+  name?: string;
+  url?: string;
+  feed_token?: string;
+  public_url?: string;
+  json_public_url?: string;
+  created_at?: string;
+  updated_at?: string;
+};
+
+export function createdFeedBody(overrides: CreatedFeedOverrides = {}) {
+  const timestamp = overrides.created_at ?? '2026-04-05T08:59:00.000Z';
+  const token = overrides.feed_token ?? 'generated-token';
+  return {
+    success: true,
+    data: {
+      feed: {
+        id: overrides.id ?? 'feed-123',
+        name: overrides.name ?? 'Example Feed',
+        url: overrides.url ?? 'https://example.com/articles',
+        feed_token: token,
+        public_url: overrides.public_url ?? `/api/v1/feeds/${token}`,
+        json_public_url: overrides.json_public_url ?? `/api/v1/feeds/${token}.json`,
+        created_at: timestamp,
+        updated_at: overrides.updated_at ?? '2026-04-05T09:00:00.000Z',
+      },
+    },
+  };
+}
+
+/** MSW create response includes meta.created; Playwright create uses the same feed payload. */
+export function buildFeedResponse(overrides: CreatedFeedOverrides = {}) {
+  return {
+    ...createdFeedBody(overrides),
+    meta: { created: true },
+  };
+}
+
+export type StructuredErrorOverrides = {
+  code?: string;
+  message?: string;
+  kind?: 'auth' | 'input' | 'network' | 'server';
+  retryable?: boolean;
+  next_action?: 'enter_token' | 'correct_input' | 'retry' | 'wait' | 'none';
+  retry_action?: 'alternate' | 'primary' | 'none';
+};
+
+export function buildStructuredErrorResponse(overrides: StructuredErrorOverrides = {}) {
+  return {
+    success: false,
+    error: {
+      code: overrides.code ?? 'INTERNAL_SERVER_ERROR',
+      message: overrides.message ?? 'Internal Server Error',
+      kind: overrides.kind ?? 'server',
+      retryable: overrides.retryable ?? false,
+      next_action: overrides.next_action ?? 'none',
+      retry_action: overrides.retry_action ?? 'none',
+    },
+  };
+}
+
+export function validateSuccessBody(
+  selectors: unknown = { items: { selector: 'article' } },
+  yaml = 'selectors:\n  items:\n    selector: article\n'
+) {
+  return {
+    success: true,
+    data: {
+      report: { success: true, issues: [] },
+      selectors,
+      yaml,
+    },
+  };
+}
+
+export function suggestSuccessBody(
+  selector = 'article',
+  isEnhanced = false,
+  extras: Record<string, unknown> = {}
+) {
+  return {
+    success: true,
+    data: {
+      selectors: { items: { selector, enhance: isEnhanced } },
+      segment_strategy: 'list',
+      admission_drops: { chrome: 0 },
+      enhance: isEnhanced,
+      ...extras,
+    },
+  };
+}
+
+export function studioPreviewSuccessBody(
+  items: Array<Record<string, unknown>> = [
+    {
+      title: 'Refine meadow item',
+      url: 'https://example.com/refine-item',
+      published_at: '2024-01-02',
+    },
+  ]
+) {
+  return {
+    success: true,
+    data: {
+      item_count: items.length,
+      sample_items: items,
+      quality_report: { warnings: [], metrics: { short_title_count: 0 } },
+      failure_kind: '',
+      validation_issues: [],
+    },
+  };
+}
+
+export const jsonPreviewItems = {
+  items: [
+    {
+      title: 'Sample preview item',
+      content_text: 'Current preview fetch includes rendered content.',
+      date_published: '2026-04-05T09:00:00.000Z',
+      url: 'https://example.com/articles/sample-preview-item',
+    },
+  ],
+};
diff --git a/frontend/src/__tests__/mocks/server.ts b/frontend/src/__tests__/mocks/server.ts
index 9ab39273..5d338fcf 100644
--- a/frontend/src/__tests__/mocks/server.ts
+++ b/frontend/src/__tests__/mocks/server.ts
@@ -1,124 +1,41 @@
 import { setupServer } from 'msw/node';
 import { http, HttpResponse } from 'msw';
+import {
+  buildFeedResponse,
+  buildStructuredErrorResponse,
+  emptyCatalog,
+  metadataBody,
+  studioPreviewSuccessBody,
+  suggestSuccessBody,
+  validateSuccessBody,
+  type CreatedFeedOverrides,
+  type StructuredErrorOverrides,
+} from './apiFixtures';
 
 export const server = setupServer(
   http.get(/\/api\/v1\/?$/, () => {
-    return HttpResponse.json({
-      success: true,
-      data: {
-        api: {
-          name: 'html2rss-web API',
-          description: 'RESTful API for converting websites to RSS feeds',
-          openapi_url: 'https://example.test/openapi.yaml',
-        },
-        instance: {
-          feed_creation: {
-            enabled: true,
-            access_token_required: true,
-          },
-          studio: {
-            enabled: true,
-          },
-          catalog: {
-            enabled: true,
-            url: '/api/v1/configs',
-          },
-        },
-      },
-    });
+    return HttpResponse.json(metadataBody({ openapiUrl: 'https://example.test/openapi.yaml' }));
   }),
   http.get('/api/v1/configs', () => {
-    return HttpResponse.json({
-      success: true,
-      data: { configs: [] },
-      meta: { total: 0, catalog_version: 2, starters: [] },
-    });
+    return HttpResponse.json(emptyCatalog);
   }),
   http.post('/api/v1/feeds/validate', () => {
-    return HttpResponse.json({
-      success: true,
-      data: {
-        report: { success: true, issues: [] },
-        selectors: { items: { selector: 'article', enhance: false } },
-        yaml: 'selectors:\n  items:\n    selector: article\n    enhance: false\n',
-      },
-    });
+    return HttpResponse.json(
+      validateSuccessBody(
+        { items: { selector: 'article', enhance: false } },
+        'selectors:\n  items:\n    selector: article\n    enhance: false\n'
+      )
+    );
   }),
   http.post('/api/v1/feeds/preview', () => {
-    return HttpResponse.json({
-      success: true,
-      data: {
-        item_count: 0,
-        sample_items: [],
-        quality_report: { warnings: [], metrics: { short_title_count: 0 } },
-        failure_kind: '',
-        validation_issues: [],
-      },
-    });
+    return HttpResponse.json(studioPreviewSuccessBody([]));
   }),
   http.post('/api/v1/feeds/suggest_selectors', () => {
-    return HttpResponse.json({
-      success: true,
-      data: {
-        selectors: { items: { selector: 'article', enhance: true } },
-        segment_strategy: 'list',
-        admission_drops: { chrome: 0 },
-        enhance: true,
-      },
-    });
+    return HttpResponse.json(suggestSuccessBody('article', true));
   })
 );
 
-export interface FeedResponseOverrides {
-  id?: string;
-  name?: string;
-  url?: string;
-  feed_token?: string;
-  public_url?: string;
-  json_public_url?: string;
-  created_at?: string;
-  updated_at?: string;
-}
+export type FeedResponseOverrides = CreatedFeedOverrides;
+export type { StructuredErrorOverrides };
 
-export interface StructuredErrorOverrides {
-  code?: string;
-  message?: string;
-  kind?: 'auth' | 'input' | 'network' | 'server';
-  retryable?: boolean;
-  next_action?: 'enter_token' | 'correct_input' | 'retry' | 'wait' | 'none';
-  retry_action?: 'alternate' | 'primary' | 'none';
-}
-
-export function buildFeedResponse(overrides: FeedResponseOverrides = {}) {
-  const timestamp = overrides.created_at ?? new Date('2024-01-01T00:00:00Z').toISOString();
-  return {
-    success: true,
-    data: {
-      feed: {
-        id: overrides.id ?? 'feed-123',
-        name: overrides.name ?? 'Example Feed',
-        url: overrides.url ?? 'https://example.com/articles',
-        feed_token: overrides.feed_token ?? 'example-token',
-        public_url: overrides.public_url ?? '/api/v1/feeds/example-token',
-        json_public_url: overrides.json_public_url ?? '/api/v1/feeds/example-token.json',
-        created_at: timestamp,
-        updated_at: overrides.updated_at ?? timestamp,
-      },
-    },
-    meta: { created: true },
-  };
-}
-
-export function buildStructuredErrorResponse(overrides: StructuredErrorOverrides = {}) {
-  return {
-    success: false,
-    error: {
-      code: overrides.code ?? 'INTERNAL_SERVER_ERROR',
-      message: overrides.message ?? 'Internal Server Error',
-      kind: overrides.kind ?? 'server',
-      retryable: overrides.retryable ?? false,
-      next_action: overrides.next_action ?? 'none',
-      retry_action: overrides.retry_action ?? 'none',
-    },
-  };
-}
+export { buildFeedResponse, buildStructuredErrorResponse };

From 223939ae00774b8efb6c02e9d0efe39b10089e5e Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 20 Sep 2026 12:19:32 +0200
Subject: [PATCH 054/108] test(frontend): streamline frontend test runners

Point CI Vitest at one combined test:run process, pin Playwright to a
single worker, and correct contributor docs for the all-suite entrypoint.
---
 docs/README.md                               |   5 +-
 frontend/e2e/smoke.spec.ts                   |  14 +-
 frontend/package.json                        |   2 +-
 frontend/playwright.config.ts                |   4 +-
 frontend/src/__tests__/App.test.tsx          | 161 +++++++++----------
 frontend/src/__tests__/ConfigStudio.test.tsx |  49 +++---
 frontend/src/__tests__/mocks/apiFixtures.ts  |   4 +-
 frontend/src/__tests__/mocks/server.ts       |  10 +-
 frontend/src/__tests__/useStudio.test.ts     |  17 +-
 9 files changed, 127 insertions(+), 139 deletions(-)

diff --git a/docs/README.md b/docs/README.md
index ed3bec3b..f3fd4401 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -59,8 +59,10 @@ Running the app directly on the host is not supported.
 | `pnpm run dev`           | Vite dev server with hot reload (port 4001). |
 | `pnpm run build`         | Build static assets into `frontend/dist/`.   |
 | `pnpm run lint`          | Run ESLint across the frontend workspace.    |
-| `pnpm run test:run`      | Unit tests (Vitest).                         |
+| `pnpm run test:run`      | All Vitest tests (unit + contract).          |
+| `pnpm run test:unit`     | Unit tests only (excludes `*.contract.test.*`). |
 | `pnpm run test:contract` | Contract tests with MSW.                     |
+| `pnpm run test:e2e`      | Playwright smoke (one worker).               |
 
 Development routing defaults:
 
@@ -106,6 +108,7 @@ make ci-ready
 | Ruby API          | RSpec + Rack::Test       | Feed creation, retrieval, auth paths.                |
 | Frontend unit     | Vitest + Testing Library | Component rendering and hooks with mocked fetch.     |
 | Frontend contract | Vitest + MSW             | End-to-end fetch flows against mocked API responses. |
+| Frontend e2e      | Playwright               | Stubbed SPA smoke: create/token/result/refine journeys. |
 | Docker smoke      | RSpec (`:docker`)        | Net::HTTP probes against the containerised service.  |
 
 ---
diff --git a/frontend/e2e/smoke.spec.ts b/frontend/e2e/smoke.spec.ts
index cf9e4aba..de13e45e 100644
--- a/frontend/e2e/smoke.spec.ts
+++ b/frontend/e2e/smoke.spec.ts
@@ -257,12 +257,8 @@ test.describe('frontend smoke', () => {
 
     const urlField = page.getByLabel(COPY.urlLabel);
     await urlField.fill(BLOG_URL);
-    await expect
-      .poll(() => suggestRequests.length, { timeout: 5000 })
-      .toBeGreaterThan(suggestBeforeEdit);
-    await expect
-      .poll(() => previewRequests.length, { timeout: 5000 })
-      .toBeGreaterThan(previewBeforeEdit);
+    await expect.poll(() => suggestRequests.length, { timeout: 5000 }).toBeGreaterThan(suggestBeforeEdit);
+    await expect.poll(() => previewRequests.length, { timeout: 5000 }).toBeGreaterThan(previewBeforeEdit);
 
     const latestSuggest = suggestRequests.at(-1);
     expect(latestSuggest).toBeDefined();
@@ -272,7 +268,7 @@ test.describe('frontend smoke', () => {
     await expect(page.locator('.result-shell[data-state="refine"]')).toBeVisible();
     await expect(page.getByRole('button', { name: COPY.saveAndGenerate })).toHaveCount(1);
 
-    await urlField.fill('   ');
+    await urlField.fill(' '.repeat(3));
     await urlField.blur();
 
     await expect(page).toHaveURL(/\/#\/create$/);
@@ -282,9 +278,7 @@ test.describe('frontend smoke', () => {
     await expect(page.getByRole('button', { name: COPY.createFeed })).toBeVisible();
   });
 
-  test('hides refine when studio is disabled and bounces forced refine onto create', async ({
-    page,
-  }) => {
+  test('hides refine when studio is disabled and bounces forced refine onto create', async ({ page }) => {
     await createReadyResult(page, { isStudioEnabled: false });
 
     await expect(page.getByText(COPY.feedReady)).toBeVisible();
diff --git a/frontend/package.json b/frontend/package.json
index 61d86cdb..a0094175 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -20,7 +20,7 @@
     "test:run": "vitest run",
     "test:unit": "vitest run --reporter=verbose --config vitest.unit.config.ts",
     "test:contract": "vitest run --reporter=verbose --config vitest.contract.config.ts",
-    "test:ci": "pnpm run test:unit && pnpm run test:contract",
+    "test:ci": "pnpm run test:run",
     "test:e2e": "playwright test"
   },
   "dependencies": {
diff --git a/frontend/playwright.config.ts b/frontend/playwright.config.ts
index 81da0b8e..0d2116d5 100644
--- a/frontend/playwright.config.ts
+++ b/frontend/playwright.config.ts
@@ -16,10 +16,10 @@ function resolveChromiumExecutablePath(): string | undefined {
 
 export default defineConfig({
   testDir: './e2e',
-  fullyParallel: true,
+  fullyParallel: false,
   forbidOnly: !!process.env.CI,
   retries: process.env.CI ? 2 : 0,
-  workers: process.env.CI ? 1 : undefined,
+  workers: 1,
   reporter: 'list',
   use: {
     baseURL: 'http://127.0.0.1:4001',
diff --git a/frontend/src/__tests__/App.test.tsx b/frontend/src/__tests__/App.test.tsx
index 431bec1c..4d87f4d5 100644
--- a/frontend/src/__tests__/App.test.tsx
+++ b/frontend/src/__tests__/App.test.tsx
@@ -32,8 +32,7 @@ const mockUseFeedCreation = useFeedCreation as any;
 const mockUseCatalogEntries = useCatalogEntries as any;
 
 const EXAMPLE_URL = 'https://example.com/articles';
-const DIRECTORY_HREF =
-  'https://html2rss.github.io/feed-directory/#!url=http%3A%2F%2Flocalhost%3A3000%2F';
+const DIRECTORY_HREF = 'https://html2rss.github.io/feed-directory/#!url=http%3A%2F%2Flocalhost%3A3000%2F';
 
 const catalogHook = (entries: unknown[] = [], starters?: string[]) => ({
   entries,
@@ -85,11 +84,7 @@ function catalogEntry(
   };
 }
 
-const faoStarter = catalogEntry(
-  'fao.org/newsroom',
-  'FAO Newsroom',
-  'https://www.fao.org/newsroom'
-);
+const faoStarter = catalogEntry('fao.org/newsroom', 'FAO Newsroom', 'https://www.fao.org/newsroom');
 const anthropicNews = catalogEntry(
   'anthropic.com/news',
   'Anthropic — News',
@@ -115,92 +110,95 @@ async function expectCreateRemountedWithoutErrorChrome() {
   });
 }
 
-describe('App', () => {
-  const mockSaveToken = vi.fn();
-  const mockClearToken = vi.fn();
-  const mockCreateFeed = vi.fn();
-  const mockClearCreationError = vi.fn();
-  const mockClearResult = vi.fn();
-  const mockRetryPreviewFetch = vi.fn();
-  /** Mirrors useFeedCreation: reject sets error; clearError clears it (App mock was static). */
-  let creationHookError: FeedCreationError | undefined;
+const mockSaveToken = vi.fn();
+const mockClearToken = vi.fn();
+const mockCreateFeed = vi.fn();
+const mockClearCreationError = vi.fn();
+const mockClearResult = vi.fn();
+const mockRetryPreviewFetch = vi.fn();
+
+function stubAccessToken(options: { token?: string; hasToken?: boolean; error?: string } = {}) {
+  mockUseAccessToken.mockReturnValue({
+    token: options.token,
+    hasToken: options.hasToken ?? Boolean(options.token),
+    saveToken: mockSaveToken,
+    clearToken: mockClearToken,
+    isLoading: false,
+    error: options.error,
+  });
+}
 
-  function stubAccessToken(opts: { token?: string; hasToken?: boolean; error?: string } = {}) {
-    mockUseAccessToken.mockReturnValue({
-      token: opts.token,
-      hasToken: opts.hasToken ?? Boolean(opts.token),
-      saveToken: mockSaveToken,
-      clearToken: mockClearToken,
+function stubMetadata(
+  options: {
+    creationEnabled?: boolean;
+    tokenRequired?: boolean;
+    studioEnabled?: boolean;
+    openapiUrl?: string;
+    error?: string;
+  } = {}
+) {
+  if (options.error !== undefined) {
+    mockUseApiMetadata.mockReturnValue({
+      metadata: undefined,
       isLoading: false,
-      error: opts.error,
+      error: options.error,
     });
+    return;
   }
-
-  function stubMetadata(
-    opts: {
-      creationEnabled?: boolean;
-      tokenRequired?: boolean;
-      studioEnabled?: boolean;
-      openapiUrl?: string;
-      error?: string;
-    } = {}
-  ) {
-    if (opts.error !== undefined) {
-      mockUseApiMetadata.mockReturnValue({
-        metadata: undefined,
-        isLoading: false,
-        error: opts.error,
-      });
-      return;
-    }
-    mockUseApiMetadata.mockReturnValue({
-      metadata: {
-        api: {
-          name: 'html2rss-web API',
-          description: 'RESTful API for converting websites to RSS feeds',
-          openapi_url: opts.openapiUrl ?? 'https://example.test/openapi.yaml',
-        },
-        instance: {
-          feed_creation: {
-            enabled: opts.creationEnabled ?? true,
-            access_token_required: opts.tokenRequired ?? true,
-          },
-          studio: { enabled: opts.studioEnabled ?? true },
-          catalog: { enabled: true, url: '/api/v1/configs' },
+  mockUseApiMetadata.mockReturnValue({
+    metadata: {
+      api: {
+        name: 'html2rss-web API',
+        description: 'RESTful API for converting websites to RSS feeds',
+        openapi_url: options.openapiUrl ?? 'https://example.test/openapi.yaml',
+      },
+      instance: {
+        feed_creation: {
+          enabled: options.creationEnabled ?? true,
+          access_token_required: options.tokenRequired ?? true,
         },
+        studio: { enabled: options.studioEnabled ?? true },
+        catalog: { enabled: true, url: '/api/v1/configs' },
       },
-      isLoading: false,
-      error: undefined,
-    });
-  }
+    },
+    isLoading: false,
+    error: undefined,
+  });
+}
 
-  function stubCreation(opts: {
+function stubCreation(
+  options: {
     isCreating?: boolean;
     result?: unknown;
     error?: FeedCreationError;
-  } = {}) {
-    mockUseFeedCreation.mockReturnValue({
-      isCreating: opts.isCreating ?? false,
-      result: opts.result,
-      error: opts.error,
-      createFeed: mockCreateFeed,
-      clearError: mockClearCreationError,
-      clearResult: mockClearResult,
-      retryPreviewFetch: mockRetryPreviewFetch,
-    });
-  }
+  } = {}
+) {
+  mockUseFeedCreation.mockReturnValue({
+    isCreating: options.isCreating ?? false,
+    result: options.result,
+    error: options.error,
+    createFeed: mockCreateFeed,
+    clearError: mockClearCreationError,
+    clearResult: mockClearResult,
+    retryPreviewFetch: mockRetryPreviewFetch,
+  });
+}
 
-  function fillUrl(url = EXAMPLE_URL) {
-    fireEvent.input(screen.getByLabelText(COPY.urlLabel), { target: { value: url } });
-  }
+function fillUrl(url = EXAMPLE_URL) {
+  fireEvent.input(screen.getByLabelText(COPY.urlLabel), { target: { value: url } });
+}
 
-  function clickCreate() {
-    fireEvent.click(screen.getByRole('button', { name: COPY.createFeed }));
-  }
+function clickCreate() {
+  fireEvent.click(screen.getByRole('button', { name: COPY.createFeed }));
+}
 
-  function withMemberSession(token = 'saved-token') {
-    stubAccessToken({ token });
-  }
+function withMemberSession(token = 'saved-token') {
+  stubAccessToken({ token });
+}
+
+describe('App', () => {
+  /** Mirrors useFeedCreation: reject sets error; clearError clears it (App mock was static). */
+  let creationHookError: FeedCreationError | undefined;
 
   beforeEach(() => {
     vi.clearAllMocks();
@@ -860,8 +858,7 @@ describe('App', () => {
         retryable: false,
         nextAction: 'correct_input',
         retryAction: 'none',
-        message:
-          'Could not extract feed items. Try a more specific listing URL or explicit selectors.',
+        message: 'Could not extract feed items. Try a more specific listing URL or explicit selectors.',
       },
     });
     withMemberSession();
diff --git a/frontend/src/__tests__/ConfigStudio.test.tsx b/frontend/src/__tests__/ConfigStudio.test.tsx
index 3132e3ce..75bf5ca7 100644
--- a/frontend/src/__tests__/ConfigStudio.test.tsx
+++ b/frontend/src/__tests__/ConfigStudio.test.tsx
@@ -30,30 +30,24 @@ function suggestEnvelope(selector = 'article', isEnhanced = false, extras: Recor
   };
 }
 
-function validateEnvelope(
-  selectors: unknown = { items: { selector: 'article', enhance: false } },
-  report: { success: boolean; issues: unknown[] } = { success: true, issues: [] }
-) {
+function validateEnvelope(selectors?: unknown, report?: { success: boolean; issues: unknown[] }) {
   return {
     success: true,
     data: {
-      report,
-      selectors,
+      report: report ?? { success: true, issues: [] },
+      selectors: selectors ?? { items: { selector: 'article', enhance: false } },
       yaml: 'selectors: {}',
     },
   };
 }
 
-function previewEnvelope(
-  items: Array<Record<string, unknown>>,
-  quality: Record<string, unknown> = { warnings: [], metrics: { short_title_count: 0 } }
-) {
+function previewEnvelope(items: Array<Record<string, unknown>>, quality?: Record<string, unknown>) {
   return {
     success: true,
     data: {
       item_count: items.length,
       sample_items: items,
-      quality_report: quality,
+      quality_report: quality ?? { warnings: [], metrics: { short_title_count: 0 } },
       failure_kind: '',
       validation_issues: [],
     },
@@ -246,21 +240,24 @@ describe('ConfigStudio', () => {
     server.use(
       http.post('/api/v1/feeds/validate', () =>
         HttpResponse.json(
-          validateEnvelope({ items: { selector: 'article', enhance: false } }, {
-            success: false,
-            issues: [
-              {
-                path: ['selectors', 'title', 'selector'],
-                code: 'missing_key',
-                message: 'is missing',
-              },
-              {
-                path: ['selectors', 'url', 'selector'],
-                code: 'constraint',
-                message: 'is invalid',
-              },
-            ],
-          })
+          validateEnvelope(
+            { items: { selector: 'article', enhance: false } },
+            {
+              success: false,
+              issues: [
+                {
+                  path: ['selectors', 'title', 'selector'],
+                  code: 'missing_key',
+                  message: 'is missing',
+                },
+                {
+                  path: ['selectors', 'url', 'selector'],
+                  code: 'constraint',
+                  message: 'is invalid',
+                },
+              ],
+            }
+          )
         )
       )
     );
diff --git a/frontend/src/__tests__/mocks/apiFixtures.ts b/frontend/src/__tests__/mocks/apiFixtures.ts
index e7fe1e14..a72d26a6 100644
--- a/frontend/src/__tests__/mocks/apiFixtures.ts
+++ b/frontend/src/__tests__/mocks/apiFixtures.ts
@@ -102,14 +102,14 @@ export function buildStructuredErrorResponse(overrides: StructuredErrorOverrides
 }
 
 export function validateSuccessBody(
-  selectors: unknown = { items: { selector: 'article' } },
+  selectors?: unknown,
   yaml = 'selectors:\n  items:\n    selector: article\n'
 ) {
   return {
     success: true,
     data: {
       report: { success: true, issues: [] },
-      selectors,
+      selectors: selectors ?? { items: { selector: 'article' } },
       yaml,
     },
   };
diff --git a/frontend/src/__tests__/mocks/server.ts b/frontend/src/__tests__/mocks/server.ts
index 5d338fcf..63ca358b 100644
--- a/frontend/src/__tests__/mocks/server.ts
+++ b/frontend/src/__tests__/mocks/server.ts
@@ -1,15 +1,12 @@
 import { setupServer } from 'msw/node';
 import { http, HttpResponse } from 'msw';
 import {
-  buildFeedResponse,
-  buildStructuredErrorResponse,
   emptyCatalog,
   metadataBody,
   studioPreviewSuccessBody,
   suggestSuccessBody,
   validateSuccessBody,
   type CreatedFeedOverrides,
-  type StructuredErrorOverrides,
 } from './apiFixtures';
 
 export const server = setupServer(
@@ -36,6 +33,9 @@ export const server = setupServer(
 );
 
 export type FeedResponseOverrides = CreatedFeedOverrides;
-export type { StructuredErrorOverrides };
 
-export { buildFeedResponse, buildStructuredErrorResponse };
+export {
+  buildFeedResponse,
+  buildStructuredErrorResponse,
+  type StructuredErrorOverrides,
+} from './apiFixtures';
diff --git a/frontend/src/__tests__/useStudio.test.ts b/frontend/src/__tests__/useStudio.test.ts
index 2095afee..11d1127d 100644
--- a/frontend/src/__tests__/useStudio.test.ts
+++ b/frontend/src/__tests__/useStudio.test.ts
@@ -264,16 +264,13 @@ describe('useStudio', () => {
     mockStudioFetch(fetchMock, {
       preview: () =>
         Response.json(
-          previewBody(
-            [{ title: 'Sample', url: 'https://example.com/sample', published_at: '2024-01-02' }],
-            {
-              quality_report: {
-                warnings: [],
-                metrics: { short_title_count: 0 },
-                native_feed: 'https://example.com/feed.xml',
-              },
-            }
-          )
+          previewBody([{ title: 'Sample', url: 'https://example.com/sample', published_at: '2024-01-02' }], {
+            quality_report: {
+              warnings: [],
+              metrics: { short_title_count: 0 },
+              native_feed: 'https://example.com/feed.xml',
+            },
+          })
         ),
     });
 

From bd633cd9f5eb56c12ba0d4d5db1be209d9aacb46 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 20 Sep 2026 12:44:38 +0200
Subject: [PATCH 055/108] fix(studio): reset items selector from fresh capture

Apply was still sending the typed items selector as the suggest hint, so a bad edit could bias capture instead of a gem-fresh determination. Post an empty hint (same as auto-prefill) and clarify the control as Use determined selector.
---
 docs/design-system.md                        |  4 ++--
 frontend/src/__tests__/ConfigStudio.test.tsx | 19 ++++++++++++++++++-
 frontend/src/__tests__/useStudio.test.ts     | 16 ++++++++++++++++
 frontend/src/journey/copy.ts                 |  2 +-
 frontend/src/studio/useStudio.ts             |  6 +-----
 5 files changed, 38 insertions(+), 9 deletions(-)

diff --git a/docs/design-system.md b/docs/design-system.md
index 41397b80..8a21b35f 100644
--- a/docs/design-system.md
+++ b/docs/design-system.md
@@ -42,7 +42,7 @@ If a page looks like it came from a different product, the change is wrong even
 - **Token gate:** a native `<dialog>` over the still-mounted, inert URL task (one interactive task). Auth copy is in-field (`tokenError`); ActionFeedback stays on create. Access Token persists until Logout with no storage UI.
 - **Result:** primary CTA is **Copy feed URL**. Open feed / JSON / feed-reader are demoted secondary actions and stay available while preview loads. Preview is non-blocking confirmation only. **Refine selectors** is one quiet action beside create another.
 - **Empty extraction:** **Refine selectors** is one quiet action beside Try again when the extraction is empty. It is not offered for other create errors.
-- **Refine:** `#/refine` is memory-bound Sam recovery (see [personas.md](personas.md) J2/J3/J3b). No token in the route. Same frame as Result: a `result-shell` / `layout-stack` rail — never a mega-card bisected by the fixed footer, never a two-column paddock. First viewport leads with the live preview meadow (`.ui-item-list`) after validation, then compact controls: items selector, left-aligned **Apply suggestion**, a large Enhance hit target, and **Save and generate feed** as the only `btn--primary` in `ui-actions`. URL, native-feed Notice, and View as YAML are demoted support below the controls. Changing the URL re-suggests and re-previews without leaving refine or running catalog find; empty URL recovers onto remounted `#/create`. Prefill: an empty items selector is filled once from suggestion, and Enhance follows that suggestion until the user changes either. Wire is the typed closed selectors document (no strip/trim/affix cleanup UI). Fix a field opens one selector panel **in the stack** for Title, Link, or Published date. View as YAML is read-only and captioned as a selectors fragment — not a feeds.yml. Save-failure Notices use wire `Decision#message` — never create-journey copy. When studio is disabled on the instance, Refine actions stay hidden and `#/refine` bounces to create. Focus is the items selector.
+- **Refine:** `#/refine` is memory-bound Sam recovery (see [personas.md](personas.md) J2/J3/J3b). No token in the route. Same frame as Result: a `result-shell` / `layout-stack` rail — never a mega-card bisected by the fixed footer, never a two-column paddock. First viewport leads with the live preview meadow (`.ui-item-list`) after validation, then compact controls: items selector, left-aligned **Use determined selector**, a large Enhance hit target, and **Save and generate feed** as the only `btn--primary` in `ui-actions`. URL, native-feed Notice, and View as YAML are demoted support below the controls. Changing the URL re-suggests and re-previews without leaving refine or running catalog find; empty URL recovers onto remounted `#/create`. Prefill: an empty items selector is filled once from suggestion while untouched, and Enhance follows that suggestion until the user changes either. **Use determined selector** re-fetches capture with no items hint and overwrites items + Enhance. Wire is the typed closed selectors document (no strip/trim/affix cleanup UI). Fix a field opens one selector panel **in the stack** for Title, Link, or Published date. View as YAML is read-only and captioned as a selectors fragment — not a feeds.yml. Save-failure Notices use wire `Decision#message` — never create-journey copy. When studio is disabled on the instance, Refine actions stay hidden and `#/refine` bounces to create. Focus is the items selector.
 - **Unmatched result:** `#/result/:token` is valid only with a matching in-memory result. Missing or mismatched tokens recover onto remounted `#/create` (no API rehydrate, no failure chrome, no durable shareable result page).
 - **Status eyebrow:** one vocabulary (`Feed ready`) on the result header; preview progress lives in the preview section.
 - **Focus:** create autofocuses the URL field; token autofocuses the token field; result focuses the Copy control; refine focuses the items selector.
@@ -55,7 +55,7 @@ If a page looks like it came from a different product, the change is wrong even
 | Output | **Feed URL** |
 | Create | **Create feed** / **Creating feed** |
 | Result | **Feed ready** / **Copy feed URL** |
-| Refine | **Refine selectors** / **Save and generate feed** / **View as YAML** |
+| Refine | **Refine selectors** / **Use determined selector** / **Save and generate feed** / **View as YAML** |
 | Retry | **Try again** (button only) |
 | Preview | **Checking preview** / **Check again** |
 | Catalog | **Feed Directory** |
diff --git a/frontend/src/__tests__/ConfigStudio.test.tsx b/frontend/src/__tests__/ConfigStudio.test.tsx
index 75bf5ca7..bf1b0e93 100644
--- a/frontend/src/__tests__/ConfigStudio.test.tsx
+++ b/frontend/src/__tests__/ConfigStudio.test.tsx
@@ -227,13 +227,30 @@ describe('ConfigStudio', () => {
 
   it('applies the capture suggestion in one click', async () => {
     echoValidate();
-    stubSuggest(suggestEnvelope('.post', true, { admission_drops: { chrome: 2 } }));
+    const suggestBodies: unknown[] = [];
+    server.use(
+      http.post('/api/v1/feeds/suggest_selectors', async ({ request }) => {
+        suggestBodies.push(await request.json());
+        return HttpResponse.json(suggestEnvelope('.post', true, { admission_drops: { chrome: 2 } }));
+      })
+    );
     renderStudio();
+    await waitFor(() => expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('.post'));
+
+    fireEvent.input(screen.getByLabelText(COPY.itemsSelector), { target: { value: 'article.bad' } });
+    fireEvent.click(screen.getByLabelText(COPY.enhanceItems));
+    expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('article.bad');
+    expect(screen.getByLabelText(COPY.enhanceItems)).not.toBeChecked();
+
+    const bodyCountBeforeApply = suggestBodies.length;
     fireEvent.click(screen.getByRole('button', { name: COPY.applySuggestion }));
 
     await waitFor(() => expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('.post'));
     expect(screen.getByLabelText(COPY.enhanceItems)).toBeChecked();
     expect(screen.queryByText(/chrome/)).not.toBeInTheDocument();
+    expect(suggestBodies.slice(bodyCountBeforeApply)).toEqual(
+      expect.arrayContaining([expect.objectContaining({ items_selector: '' })])
+    );
   });
 
   it('opens a fix-a-field selector panel without cleanup controls', async () => {
diff --git a/frontend/src/__tests__/useStudio.test.ts b/frontend/src/__tests__/useStudio.test.ts
index 11d1127d..f09a885f 100644
--- a/frontend/src/__tests__/useStudio.test.ts
+++ b/frontend/src/__tests__/useStudio.test.ts
@@ -412,12 +412,28 @@ describe('useStudio', () => {
     );
     await waitFor(() => expect(result.current.state.phase).toBe('editing'));
 
+    act(() => {
+      result.current.setItemsSelector('article.bad');
+      result.current.setEnhance(false);
+    });
+    expect(result.current.state.draft.itemsSelector).toBe('article.bad');
+    expect(result.current.state.draft.enhance).toBe(false);
+
+    const suggestCountBeforeApply = callsTo(fetchMock, '/feeds/suggest_selectors').length;
     act(() => {
       result.current.requestSuggestion();
     });
 
     await waitFor(() => expect(result.current.state.draft.itemsSelector).toBe('.post'));
     expect(result.current.state.draft.enhance).toBe(true);
+
+    const applyCall = callsTo(fetchMock, '/feeds/suggest_selectors')[suggestCountBeforeApply]?.[0];
+    expect(applyCall).toBeInstanceOf(Request);
+    if (!(applyCall instanceof Request)) return;
+    expect(JSON.parse(await applyCall.clone().text())).toEqual({
+      url: pageUrl,
+      items_selector: '',
+    });
   });
 
   it('fails closed when validate is unauthorized', async () => {
diff --git a/frontend/src/journey/copy.ts b/frontend/src/journey/copy.ts
index b3162a9b..60db7831 100644
--- a/frontend/src/journey/copy.ts
+++ b/frontend/src/journey/copy.ts
@@ -70,7 +70,7 @@ export const COPY = {
   previewRegion: 'Feed preview',
   itemsSelector: 'Items selector',
   enhanceItems: 'Enhance items',
-  applySuggestion: 'Apply suggestion',
+  applySuggestion: 'Use determined selector',
   saveAndGenerate: 'Save and generate feed',
   viewAsYaml: 'View as YAML',
   yamlFragmentCaption: 'Selectors fragment — not a feeds.yml config',
diff --git a/frontend/src/studio/useStudio.ts b/frontend/src/studio/useStudio.ts
index ee01603b..3f83fb55 100644
--- a/frontend/src/studio/useStudio.ts
+++ b/frontend/src/studio/useStudio.ts
@@ -241,11 +241,7 @@ export function useStudio({
   async function requestSuggestion() {
     const requestId = ++suggestRequestReference.current;
     try {
-      const nextSuggestion = await suggestStudioSelectors(
-        token,
-        url,
-        stateReference.current.draft.itemsSelector
-      );
+      const nextSuggestion = await suggestStudioSelectors(token, url, '');
       if (suggestRequestReference.current !== requestId) return;
       itemsTouchedReference.current = true;
       enhanceTouchedReference.current = true;

From 59ce56dc98a5c545bdca758554660eacef46318b Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 20 Sep 2026 19:30:37 +0200
Subject: [PATCH 056/108] feat(studio): expand authenticated preview samples

Authenticated live preview was stuck on the gem's three-item sample. PreviewFeed now owns a ten-item meadow and copies only safe HTTP(S) images from the RSS document.
---
 app/web/api/v1/preview_feed.rb   | 63 ++++++++++++++++++++++++--------
 spec/html2rss/web/api/v1_spec.rb | 50 +++++++++++++++++++++++++
 2 files changed, 98 insertions(+), 15 deletions(-)

diff --git a/app/web/api/v1/preview_feed.rb b/app/web/api/v1/preview_feed.rb
index 72b38062..62232dcc 100644
--- a/app/web/api/v1/preview_feed.rb
+++ b/app/web/api/v1/preview_feed.rb
@@ -13,6 +13,9 @@ module V1
         # Builds the config through {Feeds::GeneratorInput} and selects
         # {Html2rss::Test::Result} fields. Never forwards +#to_h+, which includes +rss:+.
         module PreviewFeed
+          # Gem samples stay at three items. Authenticated meadow size is owned here.
+          SAMPLE_LIMIT = 10
+
           class << self
             ##
             # @param request [Rack::Request]
@@ -61,7 +64,7 @@ def default_strategy
             end
 
             # Selected fields only. {Html2rss::Test::Result#to_h} also carries +rss+.
-            # Sample hashes omit images; those URLs are copied from the same RSS items.
+            # Successful previews rebuild the meadow from that RSS, capped here.
             #
             # @param result [Html2rss::Test::Result]
             # @return [Hash{Symbol=>Object}]
@@ -75,29 +78,59 @@ def preview_fields(result)
               }
             end
 
-            # Same order and cap as +sample_items+. Never includes the RSS document.
+            # RSS items when the document parsed; otherwise the gem samples. Never the RSS body.
             #
             # @param result [Html2rss::Test::Result]
             # @return [Array<Hash>]
             def sample_items_with_images(result)
-              items = result.sample_items
-              return items if items.empty?
-
-              urls = rss_image_urls(result.rss)
-              items.each_with_index.map do |item, index|
-                url = urls[index]
-                url ? item.merge('image' => url) : item
-              end
+              from_rss = samples_from_rss(result.rss)
+              return from_rss unless from_rss.nil?
+
+              result.sample_items
             end
 
             # @param rss [String, nil]
-            # @return [Array<String, nil>]
-            def rss_image_urls(rss)
-              return [] unless rss.is_a?(String) && !rss.strip.empty?
+            # @return [Array<Hash>, nil] nil asks the caller to keep gem samples
+            def samples_from_rss(rss)
+              return unless rss.is_a?(String) && !rss.strip.empty?
 
-              RSS::Parser.parse(rss, false)&.items.to_a.map { description_image_src(it) || image_enclosure_url(it) }
+              items = RSS::Parser.parse(rss, false)&.items.to_a
+              return if items.empty?
+
+              items.first(SAMPLE_LIMIT).map { sample_from_item(it) }
             rescue RSS::Error
-              []
+              nil
+            end
+
+            # @param item [RSS::Rss::Channel::Item]
+            # @return [Hash]
+            def sample_from_item(item)
+              sample = {
+                'title' => item.title.to_s.strip,
+                'url' => item_link(item),
+                'published_at' => published_at(item)
+              }
+              image = description_image_src(item) || image_enclosure_url(item)
+              image ? sample.merge('image' => image) : sample
+            end
+
+            # @param item [RSS::Rss::Channel::Item]
+            # @return [String]
+            def item_link(item)
+              link = item.link if item.respond_to?(:link)
+              link = item.url if link.to_s.strip.empty? && item.respond_to?(:url)
+              link.to_s.strip
+            end
+
+            # @param item [RSS::Rss::Channel::Item]
+            # @return [String, nil]
+            def published_at(item)
+              value = item.pubDate if item.respond_to?(:pubDate)
+              return if value.nil?
+              return value.utc.iso8601 if value.respond_to?(:utc)
+
+              text = value.to_s.strip
+              text.empty? ? nil : text
             end
 
             # First http(s) +<img src>+ in the item description. Article images are prepended there.
diff --git a/spec/html2rss/web/api/v1_spec.rb b/spec/html2rss/web/api/v1_spec.rb
index eb20a6a8..493a4a03 100644
--- a/spec/html2rss/web/api/v1_spec.rb
+++ b/spec/html2rss/web/api/v1_spec.rb
@@ -978,6 +978,34 @@ def imaged_items
       ].join
     end
 
+    def capped_preview_result
+      rss = %(<rss version="2.0"><channel><title>t</title>#{capped_items}</channel></rss>)
+      preview_result.with(item_count: 12, rss:)
+    end
+
+    def capped_items
+      (1..12).map { |index| capped_item(index) }.join
+    end
+
+    def capped_item(index)
+      %(<item><title>Item #{index}</title><link>https://example.com/#{index}</link>#{capped_image(index)}</item>)
+    end
+
+    def capped_image(index)
+      case index
+      when 1 then '<description>&lt;img src="https://cdn.example/1.jpg"&gt;</description>'
+      when 2 then '<description>&lt;img src="javascript:alert(1)"&gt;</description>'
+      when 3 then '<enclosure url="data:image/png;base64,aaaa" type="image/png" length="1"/>'
+      when 4 then '<enclosure url="http://cdn.example/4.jpg" type="image/jpeg" length="2"/>'
+      else ''
+      end
+    end
+
+    def expected_capped_rows
+      images = ['https://cdn.example/1.jpg', nil, nil, 'http://cdn.example/4.jpg', *Array.new(6)]
+      (1..10).map { |index| ["Item #{index}", images[index - 1]] }
+    end
+
     before do
       allow(Html2rss).to receive(:test).and_return(preview_result)
     end
@@ -1018,6 +1046,28 @@ def imaged_items
       expect(json.fetch('data').keys).not_to include('rss')
     end
 
+    it 'caps the meadow at ten items and keeps only http(s) images', :aggregate_failures do
+      allow(Html2rss).to receive(:test).and_return(capped_preview_result)
+      header 'Authorization', "Bearer #{admin_token}"
+      header 'Content-Type', 'application/json'
+      post '/api/v1/feeds/preview', { url: feed_url, selectors: { items: { selector: 'article' } } }.to_json
+
+      json = expect_success_response(last_response)
+      samples = json.dig('data', 'sample_items')
+      expect(json.dig('data', 'item_count')).to eq(12)
+      expect(samples.map { it.values_at('title', 'image') }).to eq(expected_capped_rows)
+    end
+
+    it 'keeps gem samples when the rss document cannot be parsed', :aggregate_failures do
+      header 'Authorization', "Bearer #{admin_token}"
+      header 'Content-Type', 'application/json'
+      post '/api/v1/feeds/preview', { url: feed_url, selectors: { items: { selector: 'article' } } }.to_json
+
+      json = expect_success_response(last_response)
+      expect(json.dig('data', 'sample_items', 0, 'title')).to eq('A')
+      expect(json.dig('data', 'sample_items', 0)).not_to have_key('image')
+    end
+
     it 'previews through the token generator config' do
       header 'Authorization', "Bearer #{admin_token}"
       header 'Content-Type', 'application/json'

From 1985e49471544b97e0e7a7059462a52d9aaad366 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 20 Sep 2026 19:32:51 +0200
Subject: [PATCH 057/108] feat(preview): distinguish member and guest richness

The JSON preview parser always capped at five items and dropped images. Audience now follows the access token used at creation, so retry cannot widen a guest meadow.
---
 .../src/__tests__/previewHydration.test.ts    | 30 +++++++++-
 .../src/__tests__/useFeedCreation.test.ts     | 55 +++++++++++++++++++
 frontend/src/api/contracts.ts                 |  4 ++
 frontend/src/feed/useFeedCreation.ts          | 21 ++++++-
 frontend/src/feeds/feedParsers.ts             | 36 ++++++++++--
 frontend/src/feeds/feedPreviewClient.ts       | 14 +++--
 6 files changed, 147 insertions(+), 13 deletions(-)

diff --git a/frontend/src/__tests__/previewHydration.test.ts b/frontend/src/__tests__/previewHydration.test.ts
index 783086a5..caae963e 100644
--- a/frontend/src/__tests__/previewHydration.test.ts
+++ b/frontend/src/__tests__/previewHydration.test.ts
@@ -43,7 +43,13 @@ describe('previewHydration', () => {
 
   it('normalizes json feed items and caps at five', () => {
     const items = normalizePreviewItems([
-      { title: 'One', content_text: 'A', date_published: '2024-01-01', url: 'https://example.com/1' },
+      {
+        title: 'One',
+        content_text: 'A',
+        date_published: '2024-01-01',
+        url: 'https://example.com/1',
+        image: 'https://cdn.example/a.jpg',
+      },
       { title: 'Two', description: 'B', publishedLabel: 'Jan 2' },
       { title: 'Three' },
       { title: 'Four' },
@@ -60,6 +66,28 @@ describe('previewHydration', () => {
       publishedLabel: '2024-01-01',
       url: 'https://example.com/1',
     });
+    expect(items[0]).not.toHaveProperty('imageUrl');
+  });
+
+  it('keeps ten member items and only safe http(s) images', () => {
+    const items = normalizePreviewItems(
+      [
+        { title: 'Safe', image: 'https://cdn.example/a.jpg' },
+        { title: 'Plain http', image: 'http://cdn.example/b.jpg' },
+        { title: 'Script', image: 'javascript:alert(1)' },
+        { title: 'Data', image: 'data:image/png;base64,aaaa' },
+        { title: 'Spaced', image: 'https://cdn.example/a b.jpg' },
+        ...Array.from({ length: 7 }, (_, index) => ({ title: `Extra ${index}` })),
+      ],
+      'member'
+    );
+
+    expect(items).toHaveLength(10);
+    expect(items[0]?.imageUrl).toBe('https://cdn.example/a.jpg');
+    expect(items[1]?.imageUrl).toBe('http://cdn.example/b.jpg');
+    expect(items[2]).not.toHaveProperty('imageUrl');
+    expect(items[3]).not.toHaveProperty('imageUrl');
+    expect(items[4]).not.toHaveProperty('imageUrl');
   });
 
   it('marks non-transient preview HTTP failures as non-retryable', async () => {
diff --git a/frontend/src/__tests__/useFeedCreation.test.ts b/frontend/src/__tests__/useFeedCreation.test.ts
index 9f45a115..8341388f 100644
--- a/frontend/src/__tests__/useFeedCreation.test.ts
+++ b/frontend/src/__tests__/useFeedCreation.test.ts
@@ -149,4 +149,59 @@ describe('useFeedCreation', () => {
     await waitFor(() => expect(result.current.result?.preview.status).toBe('preview_ready'));
     expect(fetchMock.mock.calls.filter((call) => isCreateFeedCall(call)).length).toBe(1);
   });
+
+  it('keeps the creation audience when preview is retried', async () => {
+    const richPreview = () =>
+      Response.json(
+        {
+          items: [
+            { title: 'Shown', image: 'https://cdn.example/a.jpg' },
+            ...Array.from({ length: 9 }, (_, index) => ({ title: `Extra ${index}` })),
+          ],
+        },
+        { status: 200, headers: { 'Content-Type': 'application/feed+json' } }
+      );
+
+    fetchMock
+      .mockResolvedValueOnce(createResponse())
+      .mockResolvedValueOnce(new Response('', { status: 422 }));
+
+    const { result } = renderHook(() => useFeedCreation());
+    await act(async () => {
+      await result.current.createFeed('https://example.com/articles', '   ');
+    });
+    await waitFor(() => expect(result.current.result?.preview.status).toBe('preview_failed'));
+
+    fetchMock.mockResolvedValueOnce(richPreview());
+    act(() => result.current.retryPreviewFetch());
+
+    await waitFor(() => expect(result.current.result?.preview.status).toBe('preview_ready'));
+    expect(result.current.result?.preview.items).toHaveLength(5);
+    expect(result.current.result?.preview.items[0]).not.toHaveProperty('imageUrl');
+  });
+
+  it('uses member richness when creation had an access token', async () => {
+    fetchMock.mockResolvedValueOnce(createResponse()).mockResolvedValueOnce(
+      Response.json(
+        {
+          items: [
+            { title: 'Shown', image: 'https://cdn.example/a.jpg' },
+            { title: 'Unsafe', image: 'javascript:alert(1)' },
+            ...Array.from({ length: 10 }, (_, index) => ({ title: `Extra ${index}` })),
+          ],
+        },
+        { status: 200, headers: { 'Content-Type': 'application/feed+json' } }
+      )
+    );
+
+    const { result } = renderHook(() => useFeedCreation());
+    await act(async () => {
+      await result.current.createFeed('https://example.com/articles', 'token-123');
+    });
+
+    await waitFor(() => expect(result.current.result?.preview.status).toBe('preview_ready'));
+    expect(result.current.result?.preview.items).toHaveLength(10);
+    expect(result.current.result?.preview.items[0]?.imageUrl).toBe('https://cdn.example/a.jpg');
+    expect(result.current.result?.preview.items[1]).not.toHaveProperty('imageUrl');
+  });
 });
diff --git a/frontend/src/api/contracts.ts b/frontend/src/api/contracts.ts
index c01a0555..cfd71b68 100644
--- a/frontend/src/api/contracts.ts
+++ b/frontend/src/api/contracts.ts
@@ -32,11 +32,15 @@ export type FeedCreationErrorCode =
   | 'UNKNOWN_ERROR'
   | (string & {});
 
+/** Guest stays compact. Member is the token used when the feed was created. */
+export type PreviewAudience = 'guest' | 'member';
+
 export interface FeedPreviewItem {
   title: string;
   excerpt: string;
   publishedLabel: string;
   url?: string;
+  imageUrl?: string;
 }
 
 export interface FeedPreviewWarning {
diff --git a/frontend/src/feed/useFeedCreation.ts b/frontend/src/feed/useFeedCreation.ts
index 7c4ef28d..85e29fba 100644
--- a/frontend/src/feed/useFeedCreation.ts
+++ b/frontend/src/feed/useFeedCreation.ts
@@ -1,5 +1,5 @@
 import { useEffect, useRef, useState } from 'preact/hooks';
-import type { CreatedFeedResult, FeedCreationError } from '../api/contracts';
+import type { CreatedFeedResult, FeedCreationError, PreviewAudience } from '../api/contracts';
 import type { RefinedSelectorsDocument } from '../api/generated/types.gen';
 import {
   normalizeFeedCreationError,
@@ -10,6 +10,7 @@ import {
   loadPreviewItemsWithRetry,
   PREVIEW_UNAVAILABLE_MESSAGE,
   isAbortError,
+  previewAudienceForToken,
 } from '../feeds/feedsService';
 
 interface CreationState {
@@ -25,6 +26,7 @@ interface CreationState {
 export function useFeedCreation() {
   const requestIdReference = useRef(0);
   const previewAbortControllerReference = useRef<AbortController | undefined>(undefined);
+  const previewAudienceReference = useRef<PreviewAudience>('guest');
   const [state, setState] = useState<CreationState>({ isCreating: false });
 
   const cancelPreview = () => {
@@ -48,9 +50,20 @@ export function useFeedCreation() {
 
     try {
       const feed = await requestFeedCreation(normalizedUrl, token, selectors);
+      const audience = previewAudienceForToken(token);
+      if (requestIdReference.current === requestId) {
+        previewAudienceReference.current = audience;
+      }
       const result = buildCreatedFeedResult(feed);
       commitResult(result, requestId, setState, requestIdReference);
-      void hydrateFeedPreview(feed, requestId, setState, requestIdReference, previewAbortControllerReference);
+      void hydrateFeedPreview(
+        feed,
+        audience,
+        requestId,
+        setState,
+        requestIdReference,
+        previewAbortControllerReference
+      );
       return result;
     } catch (error) {
       const structuredError = normalizeFeedCreationError(error);
@@ -84,6 +97,7 @@ export function useFeedCreation() {
 
     void hydrateFeedPreview(
       currentResult.feed,
+      previewAudienceReference.current,
       requestId,
       setState,
       requestIdReference,
@@ -104,6 +118,7 @@ export function useFeedCreation() {
 
 async function hydrateFeedPreview(
   feed: CreatedFeedResult['feed'],
+  audience: PreviewAudience,
   requestId: number,
   setState: (value: CreationState | ((previous: CreationState) => CreationState)) => void,
   requestIdReference: { current: number },
@@ -116,7 +131,7 @@ async function hydrateFeedPreview(
   commitResult(buildPreviewLoadingResult(feed), requestId, setState, requestIdReference);
 
   try {
-    const previewResult = await loadPreviewItemsWithRetry(feed.json_public_url, controller.signal);
+    const previewResult = await loadPreviewItemsWithRetry(feed.json_public_url, controller.signal, audience);
     if (requestIdReference.current !== requestId) return;
 
     commitResult(
diff --git a/frontend/src/feeds/feedParsers.ts b/frontend/src/feeds/feedParsers.ts
index 5aaa7f50..5ffa238e 100644
--- a/frontend/src/feeds/feedParsers.ts
+++ b/frontend/src/feeds/feedParsers.ts
@@ -1,4 +1,13 @@
-import type { FeedPreviewItem } from '../api/contracts';
+import type { FeedPreviewItem, PreviewAudience } from '../api/contracts';
+
+const PREVIEW_ITEM_LIMIT: Record<PreviewAudience, number> = {
+  guest: 5,
+  member: 10,
+};
+
+export function previewAudienceForToken(token: string): PreviewAudience {
+  return token.trim() ? 'member' : 'guest';
+}
 
 export function normalizeString(value: unknown): string | undefined {
   return typeof value === 'string' && value.trim() ? value.trim() : undefined;
@@ -9,16 +18,22 @@ export function normalizeBoolean(value: unknown, fallback: boolean): boolean {
   return typeof value === 'boolean' ? value : fallback;
 }
 
-export function normalizePreviewItems(items: unknown[] | undefined): FeedPreviewItem[] {
+export function normalizePreviewItems(
+  items: unknown[] | undefined,
+  audience: PreviewAudience = 'guest'
+): FeedPreviewItem[] {
   if (!Array.isArray(items)) return [];
 
   return items
-    .map((item) => normalizePreviewItem(item))
+    .map((item) => normalizePreviewItem(item, audience))
     .filter((item): item is FeedPreviewItem => item !== undefined)
-    .slice(0, 5);
+    .slice(0, PREVIEW_ITEM_LIMIT[audience]);
 }
 
-export function normalizePreviewItem(value: unknown): FeedPreviewItem | undefined {
+export function normalizePreviewItem(
+  value: unknown,
+  audience: PreviewAudience = 'guest'
+): FeedPreviewItem | undefined {
   if (!value || typeof value !== 'object') return undefined;
 
   const candidate = value as {
@@ -34,12 +49,14 @@ export function normalizePreviewItem(value: unknown): FeedPreviewItem | undefine
     date_modified?: unknown;
     dateModified?: unknown;
     url?: unknown;
+    image?: unknown;
   };
 
   const title = normalizeString(candidate.title);
   if (!title) return undefined;
 
   const url = normalizeString(candidate.url);
+  const imageUrl = audience === 'member' ? safePreviewImageUrl(candidate.image) : undefined;
 
   return {
     title,
@@ -57,5 +74,14 @@ export function normalizePreviewItem(value: unknown): FeedPreviewItem | undefine
           candidate.dateModified
       ) || '',
     ...(url && { url }),
+    ...(imageUrl && { imageUrl }),
   };
 }
+
+function safePreviewImageUrl(value: unknown): string | undefined {
+  if (typeof value !== 'string') return;
+  const url = value.trim();
+  if (!url.startsWith('https://') && !url.startsWith('http://')) return;
+  if (/[\s"'<>]/.test(url)) return;
+  return url;
+}
diff --git a/frontend/src/feeds/feedPreviewClient.ts b/frontend/src/feeds/feedPreviewClient.ts
index 7f25c9df..a9f447a4 100644
--- a/frontend/src/feeds/feedPreviewClient.ts
+++ b/frontend/src/feeds/feedPreviewClient.ts
@@ -4,6 +4,7 @@ import type {
   FeedPreviewStatus,
   FeedPreviewWarning,
   FeedRecord,
+  PreviewAudience,
 } from '../api/contracts';
 import { COPY } from '../journey/copy';
 import { buildPreviewWarning } from './feedErrors';
@@ -131,7 +132,8 @@ export function buildPreviewLoadingResult(feed: FeedRecord): CreatedFeedResult {
 
 export async function loadPreviewItemsWithRetry(
   previewUrl: string,
-  signal?: AbortSignal
+  signal?: AbortSignal,
+  audience: PreviewAudience = 'guest'
 ): Promise<PreviewLoadResult> {
   const delays = [0, ...PREVIEW_RETRY_DELAYS_MS];
   let latestRetryableFailure: PreviewLoadResult | undefined;
@@ -139,7 +141,7 @@ export async function loadPreviewItemsWithRetry(
   for (const [index, delayMs] of delays.entries()) {
     if (delayMs > 0) await wait(delayMs, signal);
 
-    const result = await loadPreviewItems(previewUrl, signal);
+    const result = await loadPreviewItems(previewUrl, signal, audience);
     if (result.status === 'preview_ready') return result;
     if (result.warnings.every((warning) => !warning.retryable)) return result;
 
@@ -156,7 +158,11 @@ export async function loadPreviewItemsWithRetry(
   );
 }
 
-export async function loadPreviewItems(previewUrl: string, signal?: AbortSignal): Promise<PreviewLoadResult> {
+export async function loadPreviewItems(
+  previewUrl: string,
+  signal?: AbortSignal,
+  audience: PreviewAudience = 'guest'
+): Promise<PreviewLoadResult> {
   let response: Response;
 
   try {
@@ -193,7 +199,7 @@ export async function loadPreviewItems(previewUrl: string, signal?: AbortSignal)
   try {
     const payload = (await response.json()) as JsonFeedResponse;
     return {
-      items: normalizePreviewItems(payload.items),
+      items: normalizePreviewItems(payload.items, audience),
       warnings: [],
       status: 'preview_ready',
     };

From d6bae487ec971c0d306e952702494c4e5f7a45c0 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 20 Sep 2026 19:40:25 +0200
Subject: [PATCH 058/108] feat(result): embed authenticated selector refinement

Successful results kept a separate refine route that competed with Copy feed URL. Token-backed studio now edits selectors under the one result meadow, and stale refine routes return there.
---
 frontend/src/__tests__/App.contract.test.tsx  |   6 +-
 frontend/src/__tests__/ResultDisplay.test.tsx | 103 ++++++++++++------
 frontend/src/__tests__/useFeedFlow.test.ts    |  45 ++++++++
 frontend/src/__tests__/useStudio.test.ts      |  24 ++++
 frontend/src/components/App.tsx               |  14 ++-
 frontend/src/components/AppPanels.tsx         |   7 +-
 frontend/src/components/ConfigStudio.tsx      |  96 +++++++++-------
 frontend/src/components/PreviewItem.tsx       |  23 +++-
 frontend/src/components/ResultDisplay.tsx     |  67 +++++++++---
 frontend/src/feed/useFeedFlow.ts              |  14 ++-
 frontend/src/studio/useStudio.ts              |  20 +++-
 11 files changed, 316 insertions(+), 103 deletions(-)

diff --git a/frontend/src/__tests__/App.contract.test.tsx b/frontend/src/__tests__/App.contract.test.tsx
index f0094708..49a756ea 100644
--- a/frontend/src/__tests__/App.contract.test.tsx
+++ b/frontend/src/__tests__/App.contract.test.tsx
@@ -211,11 +211,11 @@ describe('App contract', () => {
     fireEvent.click(screen.getByRole('button', { name: COPY.createFeed }));
 
     await screen.findByText(COPY.feedReady);
-    fireEvent.click(screen.getByRole('button', { name: COPY.refineSelectors }));
-
     const save = await screen.findByRole('button', { name: COPY.saveAndGenerate });
     await waitFor(() => expect(save).toBeEnabled());
-    expect(document.querySelector('.result-shell')).toHaveAttribute('data-state', 'refine');
+    expect(document.querySelector('.result-shell')).toHaveAttribute('data-state', 'result');
+    expect(document.querySelectorAll('.ui-item-list')).toHaveLength(1);
+    expect(screen.queryByRole('button', { name: COPY.refineSelectors })).not.toBeInTheDocument();
     expect(document.querySelector('.ui-card')).toBeNull();
     fireEvent.click(save);
 
diff --git a/frontend/src/__tests__/ResultDisplay.test.tsx b/frontend/src/__tests__/ResultDisplay.test.tsx
index e1ea5aec..df9dce0a 100644
--- a/frontend/src/__tests__/ResultDisplay.test.tsx
+++ b/frontend/src/__tests__/ResultDisplay.test.tsx
@@ -8,7 +8,6 @@ import type { FeedCreationError } from '../api/contracts';
 
 describe('ResultDisplay', () => {
   const mockOnCreateAnother = vi.fn();
-  const mockOnRefine = vi.fn();
   const mockOnRetryPreview = vi.fn();
   const mockViewModel: Extract<AppViewModel, { kind: 'result' }> = {
     kind: 'result',
@@ -79,9 +78,7 @@ describe('ResultDisplay', () => {
     render(
       <ResultDisplay
         viewModel={viewModelWithMultiplePreviewItems}
-        studioEnabled
         onCreateAnother={mockOnCreateAnother}
-        onRefine={mockOnRefine}
         onRetryPreview={mockOnRetryPreview}
       />
     );
@@ -110,9 +107,7 @@ describe('ResultDisplay', () => {
           ...mockViewModel,
           preview: { status: 'preview_loading', items: [], isLoading: true },
         }}
-        studioEnabled
         onCreateAnother={mockOnCreateAnother}
-        onRefine={mockOnRefine}
         onRetryPreview={mockOnRetryPreview}
       />
     );
@@ -138,9 +133,7 @@ describe('ResultDisplay', () => {
             },
           ],
         }}
-        studioEnabled
         onCreateAnother={mockOnCreateAnother}
-        onRefine={mockOnRefine}
         onRetryPreview={mockOnRetryPreview}
       />
     );
@@ -154,9 +147,7 @@ describe('ResultDisplay', () => {
     render(
       <ResultDisplay
         viewModel={mockViewModel}
-        studioEnabled
         onCreateAnother={mockOnCreateAnother}
-        onRefine={mockOnRefine}
         onRetryPreview={mockOnRetryPreview}
       />
     );
@@ -174,9 +165,7 @@ describe('ResultDisplay', () => {
     render(
       <ResultDisplay
         viewModel={mockViewModel}
-        studioEnabled
         onCreateAnother={mockOnCreateAnother}
-        onRefine={mockOnRefine}
         onRetryPreview={mockOnRetryPreview}
       />
     );
@@ -203,9 +192,7 @@ describe('ResultDisplay', () => {
             },
           ],
         }}
-        studioEnabled
         onCreateAnother={mockOnCreateAnother}
-        onRefine={mockOnRefine}
         onRetryPreview={mockOnRetryPreview}
       />
     );
@@ -231,9 +218,7 @@ describe('ResultDisplay', () => {
             },
           ],
         }}
-        studioEnabled
         onCreateAnother={mockOnCreateAnother}
-        onRefine={mockOnRefine}
         onRetryPreview={mockOnRetryPreview}
       />
     );
@@ -242,44 +227,57 @@ describe('ResultDisplay', () => {
     expect(screen.getByRole('button', { name: COPY.checkAgain })).toBeInTheDocument();
   });
 
-  it('offers a quiet refine action beside create another without taking copy focus', async () => {
+  it('keeps selector controls under one meadow without taking copy focus', async () => {
     render(
       <ResultDisplay
-        viewModel={mockViewModel}
-        studioEnabled
+        viewModel={{
+          ...mockViewModel,
+          preview: {
+            ...mockViewModel.preview,
+            items: [
+              {
+                ...mockViewModel.preview.items[0]!,
+                imageUrl: 'https://cdn.example/a.jpg',
+              },
+            ],
+          },
+        }}
         onCreateAnother={mockOnCreateAnother}
-        onRefine={mockOnRefine}
         onRetryPreview={mockOnRetryPreview}
+        studio={{
+          token: 'token-1',
+          url: 'https://example.com',
+          onUrlChange: vi.fn(),
+          onUrlCleared: vi.fn(),
+          onGenerate: vi.fn(async () => {}),
+        }}
       />
     );
 
-    const refine = screen.getByRole('button', { name: COPY.refineSelectors });
-    const createAnother = screen.getByRole('button', { name: COPY.createAnother });
     const copyFeedUrl = screen.getByRole('button', { name: COPY.copyFeedUrl });
-
-    expect(refine).toHaveClass('btn', 'btn--quiet', 'btn--linkish');
-    expect(refine.parentElement).toBe(createAnother.parentElement);
-    expect(refine.parentElement).toHaveClass('ui-actions');
+    expect(screen.queryByRole('button', { name: COPY.refineSelectors })).not.toBeInTheDocument();
+    expect(screen.getByLabelText(COPY.itemsSelector)).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: COPY.saveAndGenerate })).toHaveClass('btn--primary');
+    expect(document.querySelectorAll('.ui-item-list')).toHaveLength(1);
+    const image = document.querySelector('img.refine-sample-image');
+    expect(image).toHaveAttribute('src', 'https://cdn.example/a.jpg');
+    expect(image).toHaveAttribute('referrerpolicy', 'no-referrer');
     await waitFor(() => {
       expect(document.activeElement).toBe(copyFeedUrl);
     });
-
-    fireEvent.click(refine);
-    expect(mockOnRefine).toHaveBeenCalledTimes(1);
   });
 
-  it('hides refine when studio is disabled on the instance', () => {
+  it('hides selector controls when studio is unavailable', () => {
     render(
       <ResultDisplay
         viewModel={mockViewModel}
-        studioEnabled={false}
         onCreateAnother={mockOnCreateAnother}
-        onRefine={mockOnRefine}
         onRetryPreview={mockOnRetryPreview}
       />
     );
 
     expect(screen.queryByRole('button', { name: COPY.refineSelectors })).not.toBeInTheDocument();
+    expect(screen.queryByLabelText(COPY.itemsSelector)).not.toBeInTheDocument();
     expect(screen.getByRole('button', { name: COPY.createAnother })).toBeInTheDocument();
   });
 });
@@ -301,6 +299,7 @@ function renderEmptyExtractionError(error: FeedCreationError, onRefine = vi.fn()
       submitDisabled={false}
       feedCreationEnabled
       studioEnabled
+      hasAccessToken
       catalogEntries={[]}
       featuredFeeds={[]}
       tokenDraft=""
@@ -391,6 +390,48 @@ describe('empty extraction refine on-ramp', () => {
         submitDisabled={false}
         feedCreationEnabled
         studioEnabled={false}
+        hasAccessToken
+        catalogEntries={[]}
+        featuredFeeds={[]}
+        tokenDraft=""
+        onFeedSubmit={noop}
+        onFeedFieldChange={noop}
+        onTokenDraftChange={noop}
+        onSaveToken={noop}
+        onCancelTokenPrompt={noop}
+        onRetryCreate={noop}
+        onRefine={noop}
+      />
+    );
+
+    expect(screen.queryByRole('button', { name: COPY.refineSelectors })).not.toBeInTheDocument();
+  });
+
+  it('does not offer refine without an access token', () => {
+    const noop = vi.fn();
+    render(
+      <CreateFeedPanel
+        focusComposerKey={0}
+        viewModel={{
+          kind: 'error',
+          message: 'We could not extract feed items from this page yet.',
+          error: {
+            kind: 'input',
+            code: 'EXTRACTION_EMPTY',
+            retryable: true,
+            nextAction: 'retry',
+            retryAction: 'primary',
+            message: 'We could not extract feed items from this page yet.',
+          },
+          errorKind: 'input',
+        }}
+        isCreating={false}
+        feedFormData={{ url: 'https://example.com/articles' }}
+        feedFieldErrors={{ url: '', form: '' }}
+        submitDisabled={false}
+        feedCreationEnabled
+        studioEnabled
+        hasAccessToken={false}
         catalogEntries={[]}
         featuredFeeds={[]}
         tokenDraft=""
diff --git a/frontend/src/__tests__/useFeedFlow.test.ts b/frontend/src/__tests__/useFeedFlow.test.ts
index 733444b6..ad1edf29 100644
--- a/frontend/src/__tests__/useFeedFlow.test.ts
+++ b/frontend/src/__tests__/useFeedFlow.test.ts
@@ -318,4 +318,49 @@ describe('useFeedFlow', () => {
     rerender({ createEntryKey: 1, route: { kind: 'create' } });
     expect(result.current.tokenDraft).toBe('');
   });
+
+  it('replaces a stale refine route with the matching result', async () => {
+    fetchMock
+      .mockResolvedValueOnce(Response.json({ success: true, data: { feed: mockFeed } }))
+      .mockResolvedValueOnce(Response.json({ items: [] }));
+
+    const { result, rerender } = renderHook((properties: FeedFlowDependencies) => useFeedFlow(properties), {
+      initialProps: feedFlowProperties({ token: 'token-1' }),
+    });
+
+    act(() => {
+      result.current.onFeedFieldChange('url', 'https://example.com/articles');
+    });
+    await act(async () => {
+      await result.current.onFeedSubmit({ preventDefault: vi.fn() } as any);
+    });
+
+    mockNavigate.mockClear();
+    rerender(feedFlowProperties({ token: 'token-1', route: { kind: 'refine' } }));
+
+    await waitFor(() => {
+      expect(mockNavigate).toHaveBeenCalledWith(
+        { kind: 'result', feedToken: 'feed-token-1' },
+        { replace: true }
+      );
+    });
+  });
+
+  it('keeps extraction-empty refine when no result exists', async () => {
+    const { result, rerender } = renderHook((properties: FeedFlowDependencies) => useFeedFlow(properties), {
+      initialProps: feedFlowProperties({ token: 'token-1' }),
+    });
+
+    act(() => {
+      result.current.onFeedFieldChange('url', 'https://example.com/articles');
+    });
+    mockNavigate.mockClear();
+    rerender(feedFlowProperties({ token: 'token-1', route: { kind: 'refine' } }));
+
+    await act(async () => {
+      await Promise.resolve();
+    });
+    expect(mockNavigate).not.toHaveBeenCalled();
+    expect(result.current.viewModel.kind).toBe('refine');
+  });
 });
diff --git a/frontend/src/__tests__/useStudio.test.ts b/frontend/src/__tests__/useStudio.test.ts
index f09a885f..999d3e89 100644
--- a/frontend/src/__tests__/useStudio.test.ts
+++ b/frontend/src/__tests__/useStudio.test.ts
@@ -310,6 +310,30 @@ describe('useStudio', () => {
     expect(callsTo(fetchMock, '/feeds/preview')).toHaveLength(1);
   });
 
+  it('does not suggest or preview on mount when live work waits for an edit', async () => {
+    mockStudioFetch(fetchMock);
+
+    const { result } = renderHook(() =>
+      useStudio({ url: pageUrl, token, live: 'after-edit', validateDelayMs: 0, previewSettleMs: 0 })
+    );
+
+    await waitFor(() => {
+      expect(callsTo(fetchMock, '/feeds/validate').length).toBeGreaterThan(0);
+    });
+    expect(callsTo(fetchMock, '/feeds/suggest_selectors')).toHaveLength(0);
+    expect(callsTo(fetchMock, '/feeds/preview')).toHaveLength(0);
+    expect(result.current.state.live.status).toBe('idle');
+
+    act(() => {
+      result.current.setItemsSelector('article');
+    });
+
+    await waitFor(() => {
+      expect(callsTo(fetchMock, '/feeds/preview')).toHaveLength(1);
+    });
+    expect(result.current.state.live.status).toBe('ready');
+  });
+
   it('starts at a[href], auto-suggests with an empty hint, then applies the determined selector', async () => {
     const pendingSuggestion = Promise.withResolvers<Response>();
     mockStudioFetch(fetchMock, {
diff --git a/frontend/src/components/App.tsx b/frontend/src/components/App.tsx
index b534d849..75ad5340 100644
--- a/frontend/src/components/App.tsx
+++ b/frontend/src/components/App.tsx
@@ -109,13 +109,22 @@ export function App() {
       </Notice>
     );
   } else if (viewModel.kind === 'result') {
+    const studio =
+      studioEnabled && token?.trim() && sourceUrl
+        ? {
+            token,
+            url: sourceUrl,
+            onUrlChange: onStudioUrlChange,
+            onUrlCleared: onStudioUrlCleared,
+            onGenerate: generateFromStudio,
+          }
+        : undefined;
     bodyContent = (
       <ResultDisplay
         viewModel={viewModel}
-        studioEnabled={studioEnabled}
         onCreateAnother={onCreateAnother}
-        onRefine={onRefine}
         onRetryPreview={onRetryPreview}
+        studio={studio}
       />
     );
   } else if (viewModel.kind === 'refine') {
@@ -139,6 +148,7 @@ export function App() {
         submitDisabled={submitDisabled}
         feedCreationEnabled={feedCreationEnabled}
         studioEnabled={studioEnabled}
+        hasAccessToken={Boolean(token?.trim())}
         catalogEntries={catalogEntries}
         featuredFeeds={featuredFeeds}
         tokenDraft={tokenDraft}
diff --git a/frontend/src/components/AppPanels.tsx b/frontend/src/components/AppPanels.tsx
index 29d1d076..130ff096 100644
--- a/frontend/src/components/AppPanels.tsx
+++ b/frontend/src/components/AppPanels.tsx
@@ -28,6 +28,7 @@ interface CreateFeedPanelProperties {
   submitDisabled: boolean;
   feedCreationEnabled: boolean;
   studioEnabled: boolean;
+  hasAccessToken: boolean;
   catalogEntries: CatalogEntry[];
   featuredFeeds: CatalogEntry[];
   tokenDraft: string;
@@ -412,6 +413,7 @@ export function CreateFeedPanel({
   submitDisabled,
   feedCreationEnabled,
   studioEnabled,
+  hasAccessToken,
   catalogEntries,
   featuredFeeds,
   tokenDraft,
@@ -442,7 +444,10 @@ export function CreateFeedPanel({
     creationError && creationError.nextAction === 'retry' && creationError.retryAction !== 'none'
   );
   const shouldOfferRefine =
-    studioEnabled && viewModel.kind === 'error' && creationError?.code === 'EXTRACTION_EMPTY';
+    studioEnabled &&
+    hasAccessToken &&
+    viewModel.kind === 'error' &&
+    creationError?.code === 'EXTRACTION_EMPTY';
   const isCreatingFeed = !isTokenPrompt && isSubmitting;
   const tokenCreating = isTokenPrompt && flowCreating;
 
diff --git a/frontend/src/components/ConfigStudio.tsx b/frontend/src/components/ConfigStudio.tsx
index 40520fee..62de00ef 100644
--- a/frontend/src/components/ConfigStudio.tsx
+++ b/frontend/src/components/ConfigStudio.tsx
@@ -1,4 +1,4 @@
-import type { JSX } from 'preact';
+import type { ComponentChildren, JSX } from 'preact';
 import { useEffect, useRef, useState } from 'preact/hooks';
 import type { RefinedSelectorsDocument } from '../api/generated/types.gen';
 import { COPY } from '../journey/copy';
@@ -11,7 +11,7 @@ import type { StudioIssue, StudioSampleItem } from '../studio/studioService';
 /** Settle delay before URL edits re-trigger suggest / validate / preview. */
 export const STUDIO_URL_SETTLE_MS = 400;
 
-interface ConfigStudioProperties {
+interface StudioControls {
   readonly url: string;
   readonly token: string;
   readonly onUrlChange: (url: string) => void;
@@ -19,15 +19,27 @@ interface ConfigStudioProperties {
   readonly onGenerate: (selectors: RefinedSelectorsDocument) => Promise<void>;
 }
 
+type ConfigStudioProperties = StudioControls &
+  (
+    | { readonly placement?: 'recovery' }
+    | { readonly placement: 'inline'; readonly fallback: ComponentChildren }
+  );
+
 interface OpenPanel {
   readonly field: StudioFieldId;
   readonly nonce: number;
 }
 
-export function ConfigStudio({ url, token, onUrlChange, onUrlCleared, onGenerate }: ConfigStudioProperties) {
+export function ConfigStudio(properties: ConfigStudioProperties) {
+  const { url, token, onUrlChange, onUrlCleared, onGenerate } = properties;
+  const isInline = properties.placement === 'inline';
   const [urlDraft, setUrlDraft] = useState(url);
   const [settledUrl, setSettledUrl] = useState(url);
-  const studio = useStudio({ url: settledUrl, token });
+  const studio = useStudio({
+    url: settledUrl,
+    token,
+    live: isInline ? 'after-edit' : 'immediate',
+  });
   const { state } = studio;
   const issues = studioIssues(state);
   const [panel, setPanel] = useState<OpenPanel | undefined>(undefined);
@@ -62,8 +74,9 @@ export function ConfigStudio({ url, token, onUrlChange, onUrlCleared, onGenerate
   }, [urlDraft, settledUrl, onUrlChange]);
 
   useEffect(() => {
+    if (isInline) return;
     itemsReference.current?.focus();
-  }, []);
+  }, [isInline]);
 
   useEffect(() => {
     if (!panel) return;
@@ -104,19 +117,10 @@ export function ConfigStudio({ url, token, onUrlChange, onUrlCleared, onGenerate
     return true;
   };
 
-  return (
-    <section
-      class="result-shell layout-stack"
-      data-state="refine"
-      aria-labelledby="refine-title"
-      aria-busy={isBusy}
-    >
-      <header class="layout-rail-reading layout-stack layout-stack--tight">
-        <h1 id="refine-title" class="ui-display-title">
-          {COPY.refineSelectors}
-        </h1>
-      </header>
-
+  const meadow =
+    isInline && state.live.status === 'idle' ? (
+      properties.fallback
+    ) : (
       <PreviewPane
         state={state}
         token={token}
@@ -124,7 +128,10 @@ export function ConfigStudio({ url, token, onUrlChange, onUrlCleared, onGenerate
         onOpenField={openFieldPanel}
         onRetry={studio.retryPreview}
       />
+    );
 
+  const controls = (
+    <>
       <div class="layout-rail-reading layout-stack refine-controls">
         {state.phase === 'failed' ? (
           <Notice title={COPY.createFailedTitle} tone="error">
@@ -140,7 +147,7 @@ export function ConfigStudio({ url, token, onUrlChange, onUrlCleared, onGenerate
             id="studio-items-selector"
             class="input input--mono input--lg"
             value={state.draft.itemsSelector}
-            autoFocus
+            autoFocus={!isInline}
             ref={itemsReference}
             spellcheck={false}
             onInput={(event) => studio.setItemsSelector(inputValue(event))}
@@ -256,6 +263,32 @@ export function ConfigStudio({ url, token, onUrlChange, onUrlCleared, onGenerate
           ) : undefined}
         </div>
       </div>
+    </>
+  );
+
+  if (isInline) {
+    return (
+      <div class="layout-stack" aria-busy={isBusy}>
+        {meadow}
+        {controls}
+      </div>
+    );
+  }
+
+  return (
+    <section
+      class="result-shell layout-stack"
+      data-state="refine"
+      aria-labelledby="refine-title"
+      aria-busy={isBusy}
+    >
+      <header class="layout-rail-reading layout-stack layout-stack--tight">
+        <h1 id="refine-title" class="ui-display-title">
+          {COPY.refineSelectors}
+        </h1>
+      </header>
+      {meadow}
+      {controls}
     </section>
   );
 }
@@ -320,8 +353,12 @@ function PreviewPane({
           <ul class="ui-item-list" role="list">
             {items.map((item, index) => (
               <li key={sampleKey(item, index)} class="ui-item">
-                {canShowImages && item.imageUrl ? <SampleImage url={item.imageUrl} /> : undefined}
-                <PreviewItem title={item.title} url={item.url} publishedLabel={item.publishedAt} />
+                <PreviewItem
+                  title={item.title}
+                  url={item.url}
+                  publishedLabel={item.publishedAt}
+                  imageUrl={canShowImages ? item.imageUrl : undefined}
+                />
                 {item.url ? <p class="ui-item__meta input--mono">{item.url}</p> : undefined}
               </li>
             ))}
@@ -332,23 +369,6 @@ function PreviewPane({
   );
 }
 
-function SampleImage({ url }: { readonly url: string }) {
-  const [visible, setVisible] = useState(true);
-  if (!visible) return;
-
-  return (
-    <img
-      class="refine-sample-image"
-      alt=""
-      src={url}
-      referrerPolicy="no-referrer"
-      loading="lazy"
-      crossOrigin="anonymous"
-      onError={() => setVisible(false)}
-    />
-  );
-}
-
 function FieldFixPanel({
   field,
   selector,
diff --git a/frontend/src/components/PreviewItem.tsx b/frontend/src/components/PreviewItem.tsx
index cf5a14e7..ec827abf 100644
--- a/frontend/src/components/PreviewItem.tsx
+++ b/frontend/src/components/PreviewItem.tsx
@@ -1,13 +1,17 @@
+import { useState } from 'preact/hooks';
+
 interface PreviewItemProperties {
   title: string;
   excerpt?: string;
   url?: string;
   publishedLabel?: string;
+  imageUrl?: string;
 }
 
-export function PreviewItem({ title, excerpt, url, publishedLabel }: PreviewItemProperties) {
+export function PreviewItem({ title, excerpt, url, publishedLabel, imageUrl }: PreviewItemProperties) {
   return (
     <>
+      {imageUrl ? <SampleImage url={imageUrl} /> : undefined}
       {publishedLabel && (
         <p class="ui-item__meta">
           <time>{publishedLabel}</time>
@@ -26,3 +30,20 @@ export function PreviewItem({ title, excerpt, url, publishedLabel }: PreviewItem
     </>
   );
 }
+
+function SampleImage({ url }: { readonly url: string }) {
+  const [visible, setVisible] = useState(true);
+  if (!visible) return;
+
+  return (
+    <img
+      class="refine-sample-image"
+      alt=""
+      src={url}
+      referrerPolicy="no-referrer"
+      loading="lazy"
+      crossOrigin="anonymous"
+      onError={() => setVisible(false)}
+    />
+  );
+}
diff --git a/frontend/src/components/ResultDisplay.tsx b/frontend/src/components/ResultDisplay.tsx
index f37ba4bf..9b790896 100644
--- a/frontend/src/components/ResultDisplay.tsx
+++ b/frontend/src/components/ResultDisplay.tsx
@@ -1,16 +1,27 @@
 import type { ComponentChildren } from 'preact';
 import { useEffect, useRef, useState } from 'preact/hooks';
+import type { FeedPreviewState, FeedPreviewWarning } from '../api/contracts';
+import type { RefinedSelectorsDocument } from '../api/generated/types.gen';
 import type { AppViewModel } from '../feed';
 import { COPY } from '../journey/copy';
+import { ConfigStudio } from './ConfigStudio';
 import { DominantField } from './DominantField';
 import { PreviewItem } from './PreviewItem';
 
+/** One authenticated studio session. Absent means guest or studio-off: no selector controls. */
+export interface AuthenticatedStudioCapability {
+  readonly token: string;
+  readonly url: string;
+  readonly onUrlChange: (url: string) => void;
+  readonly onUrlCleared: () => void;
+  readonly onGenerate: (selectors: RefinedSelectorsDocument) => Promise<void>;
+}
+
 interface ResultDisplayProperties {
   viewModel: Extract<AppViewModel, { kind: 'result' }>;
-  studioEnabled: boolean;
   onCreateAnother: () => void;
-  onRefine: () => void;
   onRetryPreview: () => void;
+  studio?: AuthenticatedStudioCapability;
 }
 
 interface PreviewSectionProperties {
@@ -30,10 +41,9 @@ function PreviewSection({ ariaLabel, eyebrow, children }: PreviewSectionProperti
 
 export function ResultDisplay({
   viewModel,
-  studioEnabled,
   onCreateAnother,
-  onRefine,
   onRetryPreview,
+  studio,
 }: ResultDisplayProperties) {
   const [copied, setCopied] = useState(false);
   const copyResetReference = useRef<ReturnType<typeof globalThis.setTimeout> | undefined>(undefined);
@@ -47,12 +57,6 @@ export function ResultDisplay({
     ? feed.json_public_url
     : `${location.origin}${feed.json_public_url}`;
   const subscribeUrl = /^https?:\/\//i.test(fullUrl) ? `feed:${fullUrl}` : undefined;
-  const canManuallyRetryPreview =
-    preview.status === 'preview_failed' && warnings.some((warning) => warning.retryable);
-  const previewMessage = warnings[0]?.message ?? '';
-  const hasPreviewItems = preview.items.length > 0;
-  const isShowPreviewError =
-    preview.status === 'preview_failed' && !preview.isLoading && !hasPreviewItems && !!previewMessage;
 
   useEffect(() => {
     copyButtonReference.current?.focus();
@@ -104,16 +108,46 @@ export function ResultDisplay({
             {COPY.openInFeedReader}
           </a>
         )}
-        {studioEnabled ? (
-          <button type="button" class="btn btn--quiet btn--linkish" onClick={onRefine}>
-            {COPY.refineSelectors}
-          </button>
-        ) : undefined}
         <button type="button" class="btn btn--quiet btn--linkish" onClick={onCreateAnother}>
           {COPY.createAnother}
         </button>
       </div>
 
+      {studio ? (
+        <ConfigStudio
+          placement="inline"
+          url={studio.url}
+          token={studio.token}
+          onUrlChange={studio.onUrlChange}
+          onUrlCleared={studio.onUrlCleared}
+          onGenerate={studio.onGenerate}
+          fallback={<ResultMeadow preview={preview} warnings={warnings} onRetryPreview={onRetryPreview} />}
+        />
+      ) : (
+        <ResultMeadow preview={preview} warnings={warnings} onRetryPreview={onRetryPreview} />
+      )}
+    </section>
+  );
+}
+
+function ResultMeadow({
+  preview,
+  warnings,
+  onRetryPreview,
+}: {
+  readonly preview: FeedPreviewState;
+  readonly warnings: readonly FeedPreviewWarning[];
+  readonly onRetryPreview: () => void;
+}) {
+  const canManuallyRetryPreview =
+    preview.status === 'preview_failed' && warnings.some((warning) => warning.retryable);
+  const previewMessage = warnings[0]?.message ?? '';
+  const hasPreviewItems = preview.items.length > 0;
+  const isShowPreviewError =
+    preview.status === 'preview_failed' && !preview.isLoading && !hasPreviewItems && !!previewMessage;
+
+  return (
+    <>
       {preview.isLoading && (
         <PreviewSection ariaLabel={COPY.previewStatus}>
           <div class="preview-feedback preview-feedback--loading">
@@ -133,6 +167,7 @@ export function ResultDisplay({
                   excerpt={item.excerpt}
                   url={item.url}
                   publishedLabel={item.publishedLabel}
+                  imageUrl={item.imageUrl}
                 />
               </li>
             ))}
@@ -152,6 +187,6 @@ export function ResultDisplay({
           </div>
         </PreviewSection>
       )}
-    </section>
+    </>
   );
 }
diff --git a/frontend/src/feed/useFeedFlow.ts b/frontend/src/feed/useFeedFlow.ts
index 3857d2e4..14023916 100644
--- a/frontend/src/feed/useFeedFlow.ts
+++ b/frontend/src/feed/useFeedFlow.ts
@@ -206,18 +206,22 @@ export function useFeedFlow({
     navigate({ kind: 'create' }, { replace: true });
   }, [navigate, result, route]);
 
-  // Recover refine routes when studio is off or no in-memory URL onto remounted create.
+  // Recover refine onto the result that already owns refinement, or create when recovery is unavailable.
   useEffect(() => {
     if (route.kind !== 'refine') return;
-    if (!studioEnabled) {
+    if (!studioEnabled || !token?.trim()) {
       navigate({ kind: 'create' }, { replace: true });
       return;
     }
-    if (inMemorySourceUrl(feedFormData.url, result?.feed.url)) return;
+    if (result) {
+      navigate({ kind: 'result', feedToken: result.feed.feed_token }, { replace: true });
+      return;
+    }
+    if (inMemorySourceUrl(feedFormData.url, undefined)) return;
 
     // Do not carry a prefill URL — that would re-trigger auto-submit.
     navigate({ kind: 'create' }, { replace: true });
-  }, [feedFormData.url, navigate, result, route, studioEnabled]);
+  }, [feedFormData.url, navigate, result, route, studioEnabled, token]);
 
   useEffect(() => {
     const previousKind = previousRouteKindReference.current;
@@ -324,7 +328,7 @@ export function useFeedFlow({
       navigate({ kind: 'create', prefillUrl: feedFormData.url || undefined });
     },
     onRefine: () => {
-      if (!studioEnabled) return;
+      if (!studioEnabled || !token?.trim() || result) return;
       navigate({ kind: 'refine' });
     },
     onStudioUrlChange: (nextUrl: string) => {
diff --git a/frontend/src/studio/useStudio.ts b/frontend/src/studio/useStudio.ts
index 3f83fb55..cf55282c 100644
--- a/frontend/src/studio/useStudio.ts
+++ b/frontend/src/studio/useStudio.ts
@@ -50,6 +50,8 @@ interface UseStudioOptions {
   readonly token: string;
   readonly validateDelayMs?: number;
   readonly previewSettleMs?: number;
+  /** `after-edit` skips mount-time suggest and live preview so a result meadow can stay single. */
+  readonly live?: 'immediate' | 'after-edit';
 }
 
 export function useStudio({
@@ -57,6 +59,7 @@ export function useStudio({
   token,
   validateDelayMs = STUDIO_VALIDATE_DELAY_MS,
   previewSettleMs = STUDIO_PREVIEW_SETTLE_MS,
+  live = 'immediate',
 }: UseStudioOptions) {
   const [state, setState] = useState<StudioState>({
     phase: 'editing',
@@ -79,21 +82,25 @@ export function useStudio({
   const itemsTouchedReference = useRef(false);
   const previewSettleReference = useRef(previewSettleMs);
   previewSettleReference.current = previewSettleMs;
+  const initialUrlReference = useRef(url);
 
   useEffect(() => {
     const requestId = ++requestIdReference.current;
     const controller = new AbortController();
+    const revision = documentRevision;
     const timer = setTimeout(() => {
-      void runValidate(requestId, controller.signal);
+      void runValidate(requestId, controller.signal, revision);
     }, validateDelayMs);
 
     return () => {
       clearTimeout(timer);
       controller.abort();
     };
-  }, [documentRevision, token, url, validateDelayMs]);
+  }, [documentRevision, live, token, url, validateDelayMs]);
 
   useEffect(() => {
+    if (live === 'after-edit' && url === initialUrlReference.current) return;
+
     const requestId = ++suggestRequestReference.current;
     const controller = new AbortController();
     void loadEnhanceEvidence(requestId, controller.signal);
@@ -101,7 +108,7 @@ export function useStudio({
     return () => {
       controller.abort();
     };
-  }, [url, token]);
+  }, [live, url, token]);
 
   useEffect(() => {
     return () => {
@@ -129,7 +136,7 @@ export function useStudio({
     }
   }
 
-  async function runValidate(requestId: number, signal: AbortSignal) {
+  async function runValidate(requestId: number, signal: AbortSignal, revision: number) {
     const sentDraft = stateReference.current.draft;
     cancelPreview();
     setState((previous) => ({
@@ -142,7 +149,7 @@ export function useStudio({
     try {
       const outcome = await validateStudioSelectors(token, sentDraft, signal);
       if (signal.aborted || requestIdReference.current !== requestId) return;
-      commitValidation(outcome, sentDraft);
+      commitValidation(outcome, sentDraft, revision);
     } catch (error) {
       if (isAbortError(error) || signal.aborted || requestIdReference.current !== requestId) return;
       setState((previous) => ({
@@ -155,7 +162,7 @@ export function useStudio({
     }
   }
 
-  function commitValidation(outcome: StudioValidationOutcome, sentDraft: StudioDraft) {
+  function commitValidation(outcome: StudioValidationOutcome, sentDraft: StudioDraft, revision: number) {
     const draft = outcome.draft ? adoptServerDraft(sentDraft, outcome.draft) : sentDraft;
     const yaml = outcome.yaml ?? stateReference.current.yaml;
 
@@ -165,6 +172,7 @@ export function useStudio({
     }
 
     setState({ phase: 'editing', draft, yaml, validated: true, live: { status: 'idle' } });
+    if (live === 'after-edit' && revision === 0 && url === initialUrlReference.current) return;
     schedulePreview();
   }
 

From f08abfe1a6038f052207b7ce2b2ac9899680d8fe Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 20 Sep 2026 19:44:53 +0200
Subject: [PATCH 059/108] docs(journey): define inline result refinement

Successful results keep selector controls on the result route, and #/refine stays extraction-empty recovery. The parity gate also required the preview tests to satisfy existing ESLint rules without dropping the accepted HTTP image case.
---
 AGENTS.md                                     |  2 +-
 CONTEXT.md                                    |  2 +-
 docs/README.md                                |  2 +-
 docs/design-system.md                         |  8 +--
 docs/personas.md                              |  6 +-
 frontend/e2e/smoke.spec.ts                    | 57 ++++++++++++-------
 .../src/__tests__/previewHydration.test.ts    |  3 +
 .../src/__tests__/useFeedCreation.test.ts     |  2 +-
 8 files changed, 52 insertions(+), 30 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index e4f3b193..c38b0b4a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -87,7 +87,7 @@ Token-holder refinement of the selectors subtree, then generate via create.
 | Disabled response | `403` when the flag is off                                                                                                            |
 | Auth              | Access token required on validate, preview, suggest, and create                                                                       |
 | Live fetch        | Preview and suggest also need `AUTO_SOURCE_ENABLED`                                                                                   |
-| Frontend          | `#/refine` is memory-bound meadow recovery; missing URL or studio-off recovers/bounces to remounted `#/create`                        |
+| Frontend          | Successful results refine inline on `#/result/:token`. `#/refine` is only authenticated extraction-empty recovery. A successful in-memory result replaces `#/refine` with that result. Missing URL, studio-off, or tokenless bounces to remounted `#/create` |
 | Contract SSOT     | Request specs under `spec/html2rss/web/api/v1_spec.rb` and generated `public/openapi.yaml`                                            |
 
 After handler or envelope changes: `make openapi` and `make ci-ready`.
diff --git a/CONTEXT.md b/CONTEXT.md
index 7b8431a5..3efee2e5 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -29,7 +29,7 @@ On create, `findCatalogEntries` matches the typed query against the catalog (URL
 Visiting create (including hashbang `#!/…` → `#/…`) bumps `createEntryKey` so the create surface remounts. Remount alone does not auto-submit; auto-submit requires `prefillUrl`.
 
 ### Config Studio
-The `#/refine` surface for editing selectors before a feed is generated. Memory-bound to the in-memory page URL (no token in the route). The visual builder and YAML are one document; only `studioService` unwraps the studio envelope. Save posts refined selectors through Creation IO and returns to the result view.
+Selector refinement for a token holder when studio is enabled. A successful result owns that refinement inline on `#/result/:token` (one meadow; live studio output replaces the result preview). `#/refine` is only extraction-empty recovery when no result exists. Memory-bound to the in-memory page URL (no token in the route). The visual builder and YAML are one document; only `studioService` unwraps the studio envelope. Save posts refined selectors through Creation IO and stays on the result view.
 
 ### Refined Selectors
 The allowlisted `selectors` document a token holder may attach on feed creation. Signed into the feed token and resolved on later serves. Not a full config: channel, headers, and strategy stay denied.
diff --git a/docs/README.md b/docs/README.md
index f3fd4401..985148f3 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -212,7 +212,7 @@ Rules:
 - `BUILD_TAG` and `GIT_SHA` are required in production so startup logs can identify the deployed build.
 - Add or change flags in code, tests, and this table together.
 
-`STUDIO_ENABLED=true` exposes the config refinement studio: `POST /api/v1/feeds/validate`, `POST /api/v1/feeds/preview`, and `POST /api/v1/feeds/suggest_selectors`. All three require a valid access token and return `403 Studio is disabled` when the flag is off. `POST /api/v1/feeds` returns the same `403` when the body carries a `selectors` object, because those selectors are studio output; a body without `selectors` stays the automatic path and keeps working with the flag off. `preview` and `suggest_selectors` additionally need `AUTO_SOURCE_ENABLED=true` because they fetch the caller's URL live, and they only accept URLs the caller's account is allowed to reach. `GET /api/v1` advertises `instance.studio.enabled` so the SPA can hide Refine and bounce `#/refine` when the flag is off. Leave the flag off in production unless you intend to let token holders run live extraction against arbitrary allowed URLs.
+`STUDIO_ENABLED=true` exposes the config refinement studio: `POST /api/v1/feeds/validate`, `POST /api/v1/feeds/preview`, and `POST /api/v1/feeds/suggest_selectors`. All three require a valid access token and return `403 Studio is disabled` when the flag is off. `POST /api/v1/feeds` returns the same `403` when the body carries a `selectors` object, because those selectors are studio output; a body without `selectors` stays the automatic path and keeps working with the flag off. `preview` and `suggest_selectors` additionally need `AUTO_SOURCE_ENABLED=true` because they fetch the caller's URL live, and they only accept URLs the caller's account is allowed to reach. Authenticated preview samples are capped at 10 items and include only safe HTTP(S) image URLs. `GET /api/v1` advertises `instance.studio.enabled` so the SPA can hide selector controls and the extraction-empty Refine action when the flag is off, and bounce `#/refine` to create. A successful in-memory result keeps refinement on `#/result/:token`. Leave the flag off in production unless you intend to let token holders run live extraction against arbitrary allowed URLs.
 
 Rate limiting still uses the shared `RATE_LIMIT_MAX_REQUESTS` budget over `RATE_LIMIT_WINDOW_SECONDS`, but each live-fetch studio request to `preview` or `suggest_selectors` consumes five request slots. This fixed weighting protects the more expensive HTTP/browser extraction paths without adding another deployment flag.
 
diff --git a/docs/design-system.md b/docs/design-system.md
index 8a21b35f..84ae389d 100644
--- a/docs/design-system.md
+++ b/docs/design-system.md
@@ -40,12 +40,12 @@ If a page looks like it came from a different product, the change is wrong even
 
 - **Create:** URL field is the task. Visiting `#/create` or `#!/create` remounts create; hashbang aliases canonicalize to `#/create`. Bare create does not auto-submit. When the typed query finds catalog entries (URL equivalence or text substring), show matching feeds as a subordinate list under the field — never a second primary task or in-app catalog browser. On an empty Create URL, up to three Feed Directory starters may appear as subordinate chrome (lean: `.ui-eyebrow` + list + demoted `utility-link` escape under the list when creation is enabled; Notice when creation is disabled). Escape and utility-strip share **Browse Feed Directory (N)** (`catalogEntries.length`); hide starters and the under-list escape while typing, when find has hits, or while creating.
 - **Token gate:** a native `<dialog>` over the still-mounted, inert URL task (one interactive task). Auth copy is in-field (`tokenError`); ActionFeedback stays on create. Access Token persists until Logout with no storage UI.
-- **Result:** primary CTA is **Copy feed URL**. Open feed / JSON / feed-reader are demoted secondary actions and stay available while preview loads. Preview is non-blocking confirmation only. **Refine selectors** is one quiet action beside create another.
-- **Empty extraction:** **Refine selectors** is one quiet action beside Try again when the extraction is empty. It is not offered for other create errors.
-- **Refine:** `#/refine` is memory-bound Sam recovery (see [personas.md](personas.md) J2/J3/J3b). No token in the route. Same frame as Result: a `result-shell` / `layout-stack` rail — never a mega-card bisected by the fixed footer, never a two-column paddock. First viewport leads with the live preview meadow (`.ui-item-list`) after validation, then compact controls: items selector, left-aligned **Use determined selector**, a large Enhance hit target, and **Save and generate feed** as the only `btn--primary` in `ui-actions`. URL, native-feed Notice, and View as YAML are demoted support below the controls. Changing the URL re-suggests and re-previews without leaving refine or running catalog find; empty URL recovers onto remounted `#/create`. Prefill: an empty items selector is filled once from suggestion while untouched, and Enhance follows that suggestion until the user changes either. **Use determined selector** re-fetches capture with no items hint and overwrites items + Enhance. Wire is the typed closed selectors document (no strip/trim/affix cleanup UI). Fix a field opens one selector panel **in the stack** for Title, Link, or Published date. View as YAML is read-only and captioned as a selectors fragment — not a feeds.yml. Save-failure Notices use wire `Decision#message` — never create-journey copy. When studio is disabled on the instance, Refine actions stay hidden and `#/refine` bounces to create. Focus is the items selector.
+- **Result:** primary CTA is **Copy feed URL**, and it takes initial focus. Open feed / JSON / feed-reader are demoted secondary actions and stay available while preview loads. Preview is one meadow and non-blocking confirmation only. Guest results stay compact: at most 5 items, no images, no selector controls. An authenticated, studio-enabled result keeps that same frame and adds selector controls below the meadow. Selector edits replace the meadow with live studio output; they do not add a second list. **Save and generate feed** is the only primary action inside those controls. Member previews may show up to 10 items and safe HTTP(S) images.
+- **Empty extraction:** **Refine selectors** is one quiet action beside Try again when the extraction is empty, studio is enabled, and an access token is present. It is not offered for other create errors, guests, or a studio-off instance.
+- **Refine:** `#/refine` is memory-bound extraction-empty recovery for an authenticated studio (see [personas.md](personas.md) J2). No token in the route. A successful in-memory result replaces `#/refine` with `#/result/:token`; refinement of that feed stays on the result. Standalone recovery uses the same frame as Result: a `result-shell` / `layout-stack` rail — never a mega-card bisected by the fixed footer, never a two-column paddock. First viewport leads with the live preview meadow (`.ui-item-list`) after validation, then compact controls: items selector, left-aligned **Use determined selector**, a large Enhance hit target, and **Save and generate feed** as the only `btn--primary` in `ui-actions`. URL, native-feed Notice, and View as YAML are demoted support below the controls. Changing the URL re-suggests and re-previews without leaving the current surface or running catalog find; empty URL recovers onto remounted `#/create`. Prefill: an empty items selector is filled once from suggestion while untouched, and Enhance follows that suggestion until the user changes either. **Use determined selector** re-fetches capture with no items hint and overwrites items + Enhance. Wire is the typed closed selectors document (no strip/trim/affix cleanup UI). Fix a field opens one selector panel **in the stack** for Title, Link, or Published date. View as YAML is read-only and captioned as a selectors fragment — not a feeds.yml. Save-failure Notices use wire `Decision#message` — never create-journey copy. When studio is disabled or the caller has no token, Refine actions stay hidden and `#/refine` bounces to create. Focus on standalone recovery is the items selector; a successful Result keeps focus on Copy.
 - **Unmatched result:** `#/result/:token` is valid only with a matching in-memory result. Missing or mismatched tokens recover onto remounted `#/create` (no API rehydrate, no failure chrome, no durable shareable result page).
 - **Status eyebrow:** one vocabulary (`Feed ready`) on the result header; preview progress lives in the preview section.
-- **Focus:** create autofocuses the URL field; token autofocuses the token field; result focuses the Copy control; refine focuses the items selector.
+- **Focus:** create autofocuses the URL field; token autofocuses the token field; result focuses the Copy control; standalone extraction-empty refine focuses the items selector.
 
 ### Vocabulary
 
diff --git a/docs/personas.md b/docs/personas.md
index f21cd0c5..26176afe 100644
--- a/docs/personas.md
+++ b/docs/personas.md
@@ -20,14 +20,14 @@ Bookmarklet is a **Sam on-ramp**, not a fifth persona.
 - **Job:** Paste a listing URL, get a feed URL, subscribe in a reader.
 - **Owning surface:** html2rss-web SPA.
 - **Golden path:** Create → token (if needed) → Result → **Copy feed URL**.
-- **Recovery only:** `#/refine` appears under **J2** (empty extraction), **J3** (wrong list or missing Title/Link/Published), and **J3b** (wrong listing URL on refine). It is not an authoring product.
+- **Recovery only:** wrong list or missing Title/Link/Published (J3) and a wrong listing URL (J3b) stay on Result for a token holder when studio is enabled. `#/refine` is only **J2** (empty extraction) when no successful result exists. It is not an authoring product.
 - **Non-goal:** Learning YAML, MCP, or directory contribution through the SPA.
 
 ## Alex — operator
 
 - **Job:** Self-host a private instance with the right flags and mounts.
 - **Owning surface:** Docker Compose / env (`AUTO_SOURCE_ENABLED`, `STUDIO_ENABLED`, `CONFIG_CATALOG_ENABLED`, access token, `feeds.yml`).
-- **html2rss-web role:** Configure capability; when studio is off, Refine stays hidden and `#/refine` bounces to create.
+- **html2rss-web role:** Configure capability; when studio is off or the caller has no token, selector controls and Refine stay hidden and `#/refine` bounces to create.
 - **Non-goal:** An in-browser config IDE as a substitute for CLI, MCP, or mounted YAML.
 
 ## Morgan — AI / MCP agent
@@ -46,4 +46,4 @@ Bookmarklet is a **Sam on-ramp**, not a fifth persona.
 
 ## SPA refine scope (Sam only)
 
-`#/refine` is documented only under Sam **J2 / J3 / J3b**. Morgan and Riley journeys never open this screen.
+`#/refine` is documented only as Sam **J2** extraction-empty recovery. J3 and J3b stay on the authenticated Result. Morgan and Riley journeys never open this screen.
diff --git a/frontend/e2e/smoke.spec.ts b/frontend/e2e/smoke.spec.ts
index de13e45e..e5953d92 100644
--- a/frontend/e2e/smoke.spec.ts
+++ b/frontend/e2e/smoke.spec.ts
@@ -57,6 +57,7 @@ async function stubStudioEndpoints(page: Page) {
 
 async function createReadyResult(page: Page, options: MetadataOptions = {}) {
   await stubSpaApi(page, { isCatalogEnabled: false, ...options });
+  if (options.isStudioEnabled !== false) await stubStudioEndpoints(page);
   await fulfillJson(page, API_FEEDS, createdFeedBody(), 201);
   await fulfillJson(page, API_JSON_PREVIEW, { items: [] }, 200, 'application/feed+json');
   await page.addInitScript(() => {
@@ -68,13 +69,6 @@ async function createReadyResult(page: Page, options: MetadataOptions = {}) {
   await expect(page.getByText(COPY.feedReady)).toBeVisible();
 }
 
-async function openRefineFromResult(page: Page) {
-  await stubStudioEndpoints(page);
-  await page.getByRole('button', { name: COPY.refineSelectors }).click();
-  await expect(page).toHaveURL(/\/#\/refine$/);
-  await expect(page.locator('.result-shell[data-state="refine"]')).toBeVisible();
-}
-
 function collectPosts(page: Page, path: RegExp, bag: Request[]) {
   page.on('request', (request) => {
     if (request.method() === 'POST' && isSameOriginApi(request.url(), path)) {
@@ -163,6 +157,7 @@ test.describe('frontend smoke', () => {
     page,
   }) => {
     await stubSpaApi(page);
+    await stubStudioEndpoints(page);
     await fulfillJson(page, API_FEEDS, createdFeedBody(), 201);
     await fulfillJson(page, API_JSON_PREVIEW, jsonPreviewItems, 200, 'application/feed+json');
 
@@ -183,11 +178,14 @@ test.describe('frontend smoke', () => {
     await expect(page.getByText(COPY.feedReady)).toBeVisible();
     await expect(page.locator('.result-shell')).toHaveAttribute('data-state', 'result');
     await expect(page.getByText('Example Feed')).toBeVisible();
-    await expect(page.getByRole('button', { name: COPY.copyFeedUrl })).toBeVisible();
+    await expect(page.getByRole('button', { name: COPY.copyFeedUrl })).toBeFocused();
     await expect(page.getByRole('link', { name: COPY.openFeed })).toBeVisible();
     await expect(page.getByRole('link', { name: COPY.openJsonFeed })).toBeVisible();
     await expect(page.getByRole('link', { name: COPY.openInFeedReader })).toBeVisible();
     await expect(page.getByRole('button', { name: COPY.createAnother })).toBeVisible();
+    await expect(page.getByRole('button', { name: COPY.refineSelectors })).toHaveCount(0);
+    await expect(page.getByLabel(COPY.itemsSelector)).toBeVisible();
+    await expect(page.locator('.ui-item-list')).toHaveCount(1);
     await expect(page.getByText('Sample preview item')).toBeVisible();
     await expect(page.getByText('Current preview fetch includes rendered content.')).toBeVisible();
 
@@ -209,16 +207,21 @@ test.describe('frontend smoke', () => {
     await expect(page.getByRole('heading', { name: COPY.refineSelectors })).toHaveCount(0);
   });
 
-  test('refines a result and generates the feed without a live scrape', async ({ page }) => {
+  test('refines a result in place and generates the feed without a live scrape', async ({ page }) => {
     await createReadyResult(page);
-    await openRefineFromResult(page);
 
+    await expect(page).toHaveURL(/\/#\/result\/generated-token$/);
+    await expect(page.locator('.result-shell')).toHaveAttribute('data-state', 'result');
+    await expect(page.getByRole('button', { name: COPY.copyFeedUrl })).toBeFocused();
+    await expect(page.getByRole('button', { name: COPY.refineSelectors })).toHaveCount(0);
     await expect(page.locator('.ui-card')).toHaveCount(0);
-    await expect(page.getByText('Refine meadow item')).toBeVisible();
-    const meadow = page.getByLabel(COPY.previewRegion, { exact: true });
+
     const items = page.getByLabel(COPY.itemsSelector);
     await expect(items).toBeVisible();
-    await expect(items).not.toHaveValue('');
+    await items.fill('article');
+    await expect(page.getByText('Refine meadow item')).toBeVisible();
+    await expect(page.locator('.ui-item-list')).toHaveCount(1);
+    const meadow = page.getByLabel(COPY.previewRegion, { exact: true });
     const meadowBox = await meadow.boundingBox();
     const itemsBox = await items.boundingBox();
     expect(meadowBox && itemsBox && meadowBox.y < itemsBox.y).toBe(true);
@@ -238,9 +241,10 @@ test.describe('frontend smoke', () => {
     await refined;
     await expect(page.getByText(COPY.feedReady)).toBeVisible();
     await expect(page).toHaveURL(/\/#\/result\/generated-token$/);
+    await expect(page.locator('.result-shell')).toHaveAttribute('data-state', 'result');
   });
 
-  test('re-suggests and re-previews after refine URL edit then remounts create on empty blur', async ({
+  test('re-suggests and re-previews after result URL edit then remounts create on empty blur', async ({
     page,
   }) => {
     const suggestRequests: Request[] = [];
@@ -249,23 +253,25 @@ test.describe('frontend smoke', () => {
     collectPosts(page, API_STUDIO_PREVIEW, previewRequests);
 
     await createReadyResult(page);
-    await openRefineFromResult(page);
-    await expect(page.getByText('Refine meadow item')).toBeVisible();
+    await expect(page).toHaveURL(/\/#\/result\/generated-token$/);
+    await expect(page.locator('.ui-item-list')).toHaveCount(0);
 
     const suggestBeforeEdit = suggestRequests.length;
     const previewBeforeEdit = previewRequests.length;
 
-    const urlField = page.getByLabel(COPY.urlLabel);
+    const urlField = page.getByRole('textbox', { name: COPY.urlLabel, exact: true });
     await urlField.fill(BLOG_URL);
     await expect.poll(() => suggestRequests.length, { timeout: 5000 }).toBeGreaterThan(suggestBeforeEdit);
     await expect.poll(() => previewRequests.length, { timeout: 5000 }).toBeGreaterThan(previewBeforeEdit);
+    await expect(page.getByText('Refine meadow item')).toBeVisible();
+    await expect(page.locator('.ui-item-list')).toHaveCount(1);
 
     const latestSuggest = suggestRequests.at(-1);
     expect(latestSuggest).toBeDefined();
     expect(latestSuggest?.postDataJSON()).toMatchObject({ url: BLOG_URL });
 
-    await expect(page).toHaveURL(/\/#\/refine$/);
-    await expect(page.locator('.result-shell[data-state="refine"]')).toBeVisible();
+    await expect(page).toHaveURL(/\/#\/result\/generated-token$/);
+    await expect(page.locator('.result-shell')).toHaveAttribute('data-state', 'result');
     await expect(page.getByRole('button', { name: COPY.saveAndGenerate })).toHaveCount(1);
 
     await urlField.fill(' '.repeat(3));
@@ -278,6 +284,19 @@ test.describe('frontend smoke', () => {
     await expect(page.getByRole('button', { name: COPY.createFeed })).toBeVisible();
   });
 
+  test('returns a stale refine hash to the matching in-memory result', async ({ page }) => {
+    await createReadyResult(page);
+
+    await page.evaluate(() => {
+      location.hash = '#/refine';
+    });
+
+    await expect(page).toHaveURL(/\/#\/result\/generated-token$/);
+    await expect(page.locator('.result-shell')).toHaveAttribute('data-state', 'result');
+    await expect(page.getByRole('heading', { name: COPY.refineSelectors })).toHaveCount(0);
+    await expect(page.getByLabel(COPY.itemsSelector)).toBeVisible();
+  });
+
   test('hides refine when studio is disabled and bounces forced refine onto create', async ({ page }) => {
     await createReadyResult(page, { isStudioEnabled: false });
 
diff --git a/frontend/src/__tests__/previewHydration.test.ts b/frontend/src/__tests__/previewHydration.test.ts
index caae963e..f1f6a136 100644
--- a/frontend/src/__tests__/previewHydration.test.ts
+++ b/frontend/src/__tests__/previewHydration.test.ts
@@ -73,6 +73,8 @@ describe('previewHydration', () => {
     const items = normalizePreviewItems(
       [
         { title: 'Safe', image: 'https://cdn.example/a.jpg' },
+        // HTTP is an accepted image scheme; the assertion below must stay non-HTTPS.
+        // eslint-disable-next-line unicorn/prefer-https
         { title: 'Plain http', image: 'http://cdn.example/b.jpg' },
         { title: 'Script', image: 'javascript:alert(1)' },
         { title: 'Data', image: 'data:image/png;base64,aaaa' },
@@ -84,6 +86,7 @@ describe('previewHydration', () => {
 
     expect(items).toHaveLength(10);
     expect(items[0]?.imageUrl).toBe('https://cdn.example/a.jpg');
+    // eslint-disable-next-line unicorn/prefer-https -- same accepted HTTP image as the fixture
     expect(items[1]?.imageUrl).toBe('http://cdn.example/b.jpg');
     expect(items[2]).not.toHaveProperty('imageUrl');
     expect(items[3]).not.toHaveProperty('imageUrl');
diff --git a/frontend/src/__tests__/useFeedCreation.test.ts b/frontend/src/__tests__/useFeedCreation.test.ts
index 8341388f..75e3ab33 100644
--- a/frontend/src/__tests__/useFeedCreation.test.ts
+++ b/frontend/src/__tests__/useFeedCreation.test.ts
@@ -168,7 +168,7 @@ describe('useFeedCreation', () => {
 
     const { result } = renderHook(() => useFeedCreation());
     await act(async () => {
-      await result.current.createFeed('https://example.com/articles', '   ');
+      await result.current.createFeed('https://example.com/articles', ' '.repeat(3));
     });
     await waitFor(() => expect(result.current.result?.preview.status).toBe('preview_failed'));
 

From 14682bc492a35dcc63619f51de5a47693ba0644d Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 20 Sep 2026 20:23:01 +0200
Subject: [PATCH 060/108] feat(result): gate selector refinement behind an
 explicit action

---
 frontend/src/__tests__/App.contract.test.tsx  | 25 +++++++--
 frontend/src/__tests__/ResultDisplay.test.tsx | 51 +++++++++++++++++-
 frontend/src/components/ResultDisplay.tsx     | 52 +++++++++++++++----
 frontend/src/styles/main.css                  |  4 ++
 4 files changed, 114 insertions(+), 18 deletions(-)

diff --git a/frontend/src/__tests__/App.contract.test.tsx b/frontend/src/__tests__/App.contract.test.tsx
index 49a756ea..d6625940 100644
--- a/frontend/src/__tests__/App.contract.test.tsx
+++ b/frontend/src/__tests__/App.contract.test.tsx
@@ -211,20 +211,35 @@ describe('App contract', () => {
     fireEvent.click(screen.getByRole('button', { name: COPY.createFeed }));
 
     await screen.findByText(COPY.feedReady);
-    const save = await screen.findByRole('button', { name: COPY.saveAndGenerate });
-    await waitFor(() => expect(save).toBeEnabled());
     expect(document.querySelector('.result-shell')).toHaveAttribute('data-state', 'result');
+    await waitFor(() => {
+      expect(document.querySelectorAll('.ui-item-list')).toHaveLength(1);
+    });
+    expect(screen.queryByLabelText(COPY.itemsSelector)).not.toBeInTheDocument();
+    expect(screen.getByRole('button', { name: COPY.refineSelectors })).toHaveAttribute(
+      'aria-expanded',
+      'false'
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: COPY.refineSelectors }));
+    const itemsSelector = await screen.findByLabelText(COPY.itemsSelector);
+    await waitFor(() => {
+      expect(itemsSelector).toHaveValue('article');
+    });
+    const save = screen.getByRole('button', { name: COPY.saveAndGenerate });
+    await waitFor(() => expect(save).toBeEnabled());
     expect(document.querySelectorAll('.ui-item-list')).toHaveLength(1);
-    expect(screen.queryByRole('button', { name: COPY.refineSelectors })).not.toBeInTheDocument();
     expect(document.querySelector('.ui-card')).toBeNull();
     fireEvent.click(save);
 
-    await screen.findByText(COPY.feedReady);
-    expect(bodies).toHaveLength(2);
+    await waitFor(() => {
+      expect(bodies).toHaveLength(2);
+    });
     expect(bodies[1]).toMatchObject({
       url: 'https://example.com/articles',
       selectors: { items: { selector: 'article' } },
     });
+    await screen.findByText(COPY.feedReady);
     fetchSpy.mockRestore();
   });
 });
diff --git a/frontend/src/__tests__/ResultDisplay.test.tsx b/frontend/src/__tests__/ResultDisplay.test.tsx
index df9dce0a..0c7e1936 100644
--- a/frontend/src/__tests__/ResultDisplay.test.tsx
+++ b/frontend/src/__tests__/ResultDisplay.test.tsx
@@ -227,7 +227,7 @@ describe('ResultDisplay', () => {
     expect(screen.getByRole('button', { name: COPY.checkAgain })).toBeInTheDocument();
   });
 
-  it('keeps selector controls under one meadow without taking copy focus', async () => {
+  it('gates selector controls behind Refine selectors without taking copy focus', async () => {
     render(
       <ResultDisplay
         viewModel={{
@@ -255,7 +255,18 @@ describe('ResultDisplay', () => {
     );
 
     const copyFeedUrl = screen.getByRole('button', { name: COPY.copyFeedUrl });
-    expect(screen.queryByRole('button', { name: COPY.refineSelectors })).not.toBeInTheDocument();
+    const refine = screen.getByRole('button', { name: COPY.refineSelectors });
+    expect(refine).toHaveClass('btn', 'btn--quiet', 'btn--linkish');
+    expect(refine).toHaveAttribute('aria-expanded', 'false');
+    expect(screen.queryByLabelText(COPY.itemsSelector)).not.toBeInTheDocument();
+    expect(document.querySelectorAll('.ui-item-list')).toHaveLength(1);
+    await waitFor(() => {
+      expect(document.activeElement).toBe(copyFeedUrl);
+    });
+
+    fireEvent.click(refine);
+
+    expect(refine).toHaveAttribute('aria-expanded', 'true');
     expect(screen.getByLabelText(COPY.itemsSelector)).toBeInTheDocument();
     expect(screen.getByRole('button', { name: COPY.saveAndGenerate })).toHaveClass('btn--primary');
     expect(document.querySelectorAll('.ui-item-list')).toHaveLength(1);
@@ -267,6 +278,42 @@ describe('ResultDisplay', () => {
     });
   });
 
+  it('keeps the selector draft mounted across collapse and expand', async () => {
+    render(
+      <ResultDisplay
+        viewModel={mockViewModel}
+        onCreateAnother={mockOnCreateAnother}
+        onRetryPreview={mockOnRetryPreview}
+        studio={{
+          token: 'token-1',
+          url: 'https://example.com',
+          onUrlChange: vi.fn(),
+          onUrlCleared: vi.fn(),
+          onGenerate: vi.fn(async () => {}),
+        }}
+      />
+    );
+
+    const refine = screen.getByRole('button', { name: COPY.refineSelectors });
+    fireEvent.click(refine);
+
+    const itemsInput = screen.getByLabelText(COPY.itemsSelector);
+    fireEvent.input(itemsInput, { target: { value: 'article.post' } });
+    expect(itemsInput).toHaveValue('article.post');
+
+    fireEvent.click(refine);
+    expect(refine).toHaveAttribute('aria-expanded', 'false');
+    const collapsedInput = document.getElementById('studio-items-selector');
+    expect(collapsedInput).not.toBeNull();
+    expect(collapsedInput).not.toBeVisible();
+    expect(document.querySelectorAll('.ui-item-list')).toHaveLength(1);
+
+    fireEvent.click(refine);
+    expect(refine).toHaveAttribute('aria-expanded', 'true');
+    expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('article.post');
+    expect(screen.getByLabelText(COPY.itemsSelector)).toBeVisible();
+  });
+
   it('hides selector controls when studio is unavailable', () => {
     render(
       <ResultDisplay
diff --git a/frontend/src/components/ResultDisplay.tsx b/frontend/src/components/ResultDisplay.tsx
index 9b790896..478bf3bb 100644
--- a/frontend/src/components/ResultDisplay.tsx
+++ b/frontend/src/components/ResultDisplay.tsx
@@ -46,10 +46,22 @@ export function ResultDisplay({
   studio,
 }: ResultDisplayProperties) {
   const [copied, setCopied] = useState(false);
+  const [refineOpen, setRefineOpen] = useState(false);
+  /** Keep studio mounted after first open so the in-memory draft survives collapse. */
+  const [refineMounted, setRefineMounted] = useState(false);
   const copyResetReference = useRef<ReturnType<typeof globalThis.setTimeout> | undefined>(undefined);
   const copyButtonReference = useRef<HTMLButtonElement>(null);
   const { feed, preview, warnings } = viewModel;
 
+  const toggleRefine = () => {
+    setRefineOpen((open) => {
+      if (!open) setRefineMounted(true);
+      return !open;
+    });
+  };
+
+  const meadow = <ResultMeadow preview={preview} warnings={warnings} onRetryPreview={onRetryPreview} />;
+
   const fullUrl = feed.public_url.startsWith('http')
     ? feed.public_url
     : `${location.origin}${feed.public_url}`;
@@ -111,20 +123,38 @@ export function ResultDisplay({
         <button type="button" class="btn btn--quiet btn--linkish" onClick={onCreateAnother}>
           {COPY.createAnother}
         </button>
+        {studio ? (
+          <button
+            type="button"
+            class="btn btn--quiet btn--linkish"
+            aria-expanded={refineOpen}
+            onClick={toggleRefine}
+          >
+            {COPY.refineSelectors}
+          </button>
+        ) : undefined}
       </div>
 
-      {studio ? (
-        <ConfigStudio
-          placement="inline"
-          url={studio.url}
-          token={studio.token}
-          onUrlChange={studio.onUrlChange}
-          onUrlCleared={studio.onUrlCleared}
-          onGenerate={studio.onGenerate}
-          fallback={<ResultMeadow preview={preview} warnings={warnings} onRetryPreview={onRetryPreview} />}
-        />
+      {studio && refineMounted ? (
+        <>
+          <div
+            class={refineOpen ? undefined : 'result-refine-panel--collapsed'}
+            {...(refineOpen ? {} : { hidden: true as const, 'aria-hidden': true as const })}
+          >
+            <ConfigStudio
+              placement="inline"
+              url={studio.url}
+              token={studio.token}
+              onUrlChange={studio.onUrlChange}
+              onUrlCleared={studio.onUrlCleared}
+              onGenerate={studio.onGenerate}
+              fallback={refineOpen ? meadow : null}
+            />
+          </div>
+          {!refineOpen && meadow}
+        </>
       ) : (
-        <ResultMeadow preview={preview} warnings={warnings} onRetryPreview={onRetryPreview} />
+        meadow
       )}
     </section>
   );
diff --git a/frontend/src/styles/main.css b/frontend/src/styles/main.css
index 2c44bc91..8393f84d 100644
--- a/frontend/src/styles/main.css
+++ b/frontend/src/styles/main.css
@@ -89,6 +89,10 @@
   gap: var(--section-gap);
 }
 
+.result-refine-panel--collapsed {
+  display: none;
+}
+
 .form-shell--minimal,
 .result-shell,
 .field-stack,

From 9b2350e4af71bd920708fd48ea78d3cf1dc2ee49 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 20 Sep 2026 20:27:48 +0200
Subject: [PATCH 061/108] refactor(studio): surface the suggested selector
 instead of overwriting silently

---
 frontend/src/__tests__/ConfigStudio.test.tsx |  48 ++--
 frontend/src/__tests__/useStudio.test.ts     |  55 ++--
 frontend/src/components/ConfigStudio.tsx     | 274 ++++++++++---------
 frontend/src/journey/copy.ts                 |   3 +-
 frontend/src/studio/selectorDraft.ts         |   8 +
 frontend/src/studio/useStudio.ts             |  51 ++--
 frontend/src/styles/main.css                 |  16 ++
 7 files changed, 243 insertions(+), 212 deletions(-)

diff --git a/frontend/src/__tests__/ConfigStudio.test.tsx b/frontend/src/__tests__/ConfigStudio.test.tsx
index bf1b0e93..95d7b86d 100644
--- a/frontend/src/__tests__/ConfigStudio.test.tsx
+++ b/frontend/src/__tests__/ConfigStudio.test.tsx
@@ -113,7 +113,7 @@ function renderStudio(
 }
 
 describe('ConfigStudio', () => {
-  it('leads with the preview meadow above the items selector when live preview is ready', async () => {
+  it('leads with the items selector above the preview meadow when live preview is ready', async () => {
     echoValidate();
     stubPreview(previewWithImage());
     renderStudio();
@@ -122,7 +122,7 @@ describe('ConfigStudio', () => {
 
     const meadow = screen.getByLabelText(COPY.previewRegion);
     const items = screen.getByLabelText(COPY.itemsSelector);
-    expect(meadow.compareDocumentPosition(items) & Node.DOCUMENT_POSITION_FOLLOWING).not.toBe(0);
+    expect(items.compareDocumentPosition(meadow) & Node.DOCUMENT_POSITION_FOLLOWING).not.toBe(0);
     expect(document.querySelector('.result-shell')).toHaveAttribute('data-state', 'refine');
     expect(document.querySelector('.ui-card')).toBeNull();
   });
@@ -142,7 +142,7 @@ describe('ConfigStudio', () => {
     await waitFor(() => expect(items).toHaveFocus());
     await waitFor(() => expect(items).toHaveValue('article'));
     expect(screen.getByLabelText(COPY.enhanceItems)).toBeInTheDocument();
-    expect(screen.getByRole('button', { name: COPY.applySuggestion })).toBeInTheDocument();
+    expect(screen.queryByRole('button', { name: COPY.useSuggestion })).toBeInTheDocument();
     expect(screen.getByRole('button', { name: COPY.fieldMissing(COPY.fieldTitle) })).toBeInTheDocument();
     expect(screen.getByRole('button', { name: COPY.fieldMissing(COPY.fieldLink) })).toBeInTheDocument();
     expect(screen.getByRole('button', { name: COPY.fieldMissing(COPY.fieldPublished) })).toBeInTheDocument();
@@ -185,7 +185,7 @@ describe('ConfigStudio', () => {
     expect(onUrlCleared).toHaveBeenCalledTimes(1);
   });
 
-  it('shows a[href] immediately then the determined selector once suggest returns', async () => {
+  it('shows a[href] immediately and a visible suggestion chip once suggest returns', async () => {
     echoValidate();
     const pendingSuggestion = Promise.withResolvers<Response>();
     server.use(http.post('/api/v1/feeds/suggest_selectors', () => pendingSuggestion.promise));
@@ -196,20 +196,23 @@ describe('ConfigStudio', () => {
 
     pendingSuggestion.resolve(HttpResponse.json(suggestEnvelope('.post', true)));
 
-    await waitFor(() => expect(items).toHaveValue('.post'));
-    expect(screen.getByLabelText(COPY.enhanceItems)).toBeChecked();
+    await waitFor(() => expect(screen.getByText('.post')).toBeInTheDocument());
+    expect(screen.getByText(COPY.suggestedSelectorLabel)).toBeInTheDocument();
+    expect(items).toHaveValue('a[href]');
+    expect(screen.getByLabelText(COPY.enhanceItems)).not.toBeChecked();
   });
 
-  it('checks enhance from suggestion and prefills an empty items selector', async () => {
+  it('shows the suggestion chip without overwriting the draft', async () => {
     echoValidate();
     stubSuggest(suggestEnvelope('.post', true, { admission_drops: { chrome: 2 } }));
     renderStudio();
 
-    await waitFor(() => expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('.post'));
-    expect(screen.getByLabelText(COPY.enhanceItems)).toBeChecked();
+    await waitFor(() => expect(screen.getByText('.post')).toBeInTheDocument());
+    expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('a[href]');
+    expect(screen.getByLabelText(COPY.enhanceItems)).not.toBeChecked();
     expect(screen.queryByText('list')).not.toBeInTheDocument();
     expect(screen.queryByText(/chrome/)).not.toBeInTheDocument();
-    expect(screen.getByRole('button', { name: COPY.applySuggestion })).toHaveClass('btn--quiet');
+    expect(screen.getByRole('button', { name: COPY.useSuggestion })).toHaveClass('btn--quiet');
     expect(screen.getByRole('button', { name: COPY.saveAndGenerate }).closest('.ui-actions')).not.toBeNull();
   });
 
@@ -221,36 +224,27 @@ describe('ConfigStudio', () => {
     fireEvent.input(screen.getByLabelText(COPY.itemsSelector), { target: { value: 'article.mine' } });
     pendingSuggestion.resolve(HttpResponse.json(suggestEnvelope('.post', true)));
 
-    await waitFor(() => expect(screen.getByLabelText(COPY.enhanceItems)).toBeChecked());
+    await waitFor(() => expect(screen.getByText('.post')).toBeInTheDocument());
     expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('article.mine');
+    expect(screen.getByLabelText(COPY.enhanceItems)).not.toBeChecked();
   });
 
-  it('applies the capture suggestion in one click', async () => {
+  it('applies the stored suggestion when Use is clicked', async () => {
     echoValidate();
-    const suggestBodies: unknown[] = [];
-    server.use(
-      http.post('/api/v1/feeds/suggest_selectors', async ({ request }) => {
-        suggestBodies.push(await request.json());
-        return HttpResponse.json(suggestEnvelope('.post', true, { admission_drops: { chrome: 2 } }));
-      })
-    );
+    stubSuggest(suggestEnvelope('.post', true, { admission_drops: { chrome: 2 } }));
     renderStudio();
-    await waitFor(() => expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('.post'));
+    await waitFor(() => expect(screen.getByRole('button', { name: COPY.useSuggestion })).toBeInTheDocument());
 
     fireEvent.input(screen.getByLabelText(COPY.itemsSelector), { target: { value: 'article.bad' } });
-    fireEvent.click(screen.getByLabelText(COPY.enhanceItems));
     expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('article.bad');
     expect(screen.getByLabelText(COPY.enhanceItems)).not.toBeChecked();
 
-    const bodyCountBeforeApply = suggestBodies.length;
-    fireEvent.click(screen.getByRole('button', { name: COPY.applySuggestion }));
+    fireEvent.click(screen.getByRole('button', { name: COPY.useSuggestion }));
 
-    await waitFor(() => expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('.post'));
+    expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('.post');
     expect(screen.getByLabelText(COPY.enhanceItems)).toBeChecked();
+    expect(screen.queryByRole('button', { name: COPY.useSuggestion })).not.toBeInTheDocument();
     expect(screen.queryByText(/chrome/)).not.toBeInTheDocument();
-    expect(suggestBodies.slice(bodyCountBeforeApply)).toEqual(
-      expect.arrayContaining([expect.objectContaining({ items_selector: '' })])
-    );
   });
 
   it('opens a fix-a-field selector panel without cleanup controls', async () => {
diff --git a/frontend/src/__tests__/useStudio.test.ts b/frontend/src/__tests__/useStudio.test.ts
index 999d3e89..7886be38 100644
--- a/frontend/src/__tests__/useStudio.test.ts
+++ b/frontend/src/__tests__/useStudio.test.ts
@@ -182,12 +182,15 @@ describe('useStudio', () => {
 
     const { result } = renderHook(() => useStudio({ url: pageUrl, token }));
     expect(callsTo(fetchMock, '/feeds/validate')).toHaveLength(0);
+    expect(result.current.state.draft.itemsSelector).toBe('a[href]');
 
     await act(async () => {
       await vi.advanceTimersByTimeAsync(0);
+      await Promise.resolve();
     });
-    expect(result.current.state.draft.itemsSelector).toBe('article');
     expect(callsTo(fetchMock, '/feeds/validate')).toHaveLength(0);
+    expect(result.current.suggestion?.itemsSelector).toBe('article');
+    expect(result.current.state.draft.itemsSelector).toBe('a[href]');
 
     await advanceValidate(STUDIO_VALIDATE_DELAY_MS - 1);
     expect(callsTo(fetchMock, '/feeds/validate')).toHaveLength(0);
@@ -202,7 +205,7 @@ describe('useStudio', () => {
     expect(fetchPath(validateInput)).toBe('/api/v1/feeds/validate');
     expect(validateInput.headers.get('Authorization')).toBe(`Bearer ${token}`);
     expect(JSON.parse(await validateInput.clone().text())).toEqual({
-      selectors: { items: { selector: 'article' } },
+      selectors: { items: { selector: 'a[href]' } },
     });
 
     const state = result.current.state;
@@ -210,7 +213,7 @@ describe('useStudio', () => {
     if (state.phase !== 'editing') return;
     expect(state.validated).toBe(true);
     expect(state.yaml).toContain('article');
-    expect(state.draft.itemsSelector).toBe('article');
+    expect(state.draft.itemsSelector).toBe('a[href]');
     expect(callsTo(fetchMock, '/feeds/preview')).toHaveLength(0);
   });
 
@@ -281,7 +284,7 @@ describe('useStudio', () => {
     await act(async () => {
       await vi.advanceTimersByTimeAsync(0);
     });
-    expect(result.current.state.draft.itemsSelector).toBe('article');
+    expect(result.current.state.draft.itemsSelector).toBe('a[href]');
 
     await advanceValidate();
     expect(callsTo(fetchMock, '/feeds/preview')).toHaveLength(0);
@@ -310,7 +313,7 @@ describe('useStudio', () => {
     expect(callsTo(fetchMock, '/feeds/preview')).toHaveLength(1);
   });
 
-  it('does not suggest or preview on mount when live work waits for an edit', async () => {
+  it('suggests on mount without preview when live work waits for an edit', async () => {
     mockStudioFetch(fetchMock);
 
     const { result } = renderHook(() =>
@@ -320,12 +323,13 @@ describe('useStudio', () => {
     await waitFor(() => {
       expect(callsTo(fetchMock, '/feeds/validate').length).toBeGreaterThan(0);
     });
-    expect(callsTo(fetchMock, '/feeds/suggest_selectors')).toHaveLength(0);
+    await waitFor(() => expect(result.current.suggestion?.itemsSelector).toBe('article'));
     expect(callsTo(fetchMock, '/feeds/preview')).toHaveLength(0);
     expect(result.current.state.live.status).toBe('idle');
+    expect(result.current.state.draft.itemsSelector).toBe('a[href]');
 
     act(() => {
-      result.current.setItemsSelector('article');
+      result.current.setItemsSelector('article.edited');
     });
 
     await waitFor(() => {
@@ -334,7 +338,7 @@ describe('useStudio', () => {
     expect(result.current.state.live.status).toBe('ready');
   });
 
-  it('starts at a[href], auto-suggests with an empty hint, then applies the determined selector', async () => {
+  it('stores a suggestion without overwriting the draft until accepted', async () => {
     const pendingSuggestion = Promise.withResolvers<Response>();
     mockStudioFetch(fetchMock, {
       suggest: () => pendingSuggestion.promise,
@@ -366,12 +370,21 @@ describe('useStudio', () => {
       pendingSuggestion.resolve(Response.json(suggestionBody(true, '.post')));
     });
 
-    await waitFor(() => expect(result.current.state.draft.itemsSelector).toBe('.post'));
-    expect(result.current.state.draft.enhance).toBe(true);
+    await waitFor(() => expect(result.current.suggestion?.itemsSelector).toBe('.post'));
+    expect(result.current.suggestion?.enhance).toBe(true);
+    expect(result.current.state.draft.itemsSelector).toBe('a[href]');
+    expect(result.current.state.draft.enhance).toBe(false);
     expect(callsTo(fetchMock, '/feeds/suggest_selectors')).toHaveLength(1);
+
+    act(() => {
+      result.current.acceptSuggestion();
+    });
+
+    expect(result.current.state.draft.itemsSelector).toBe('.post');
+    expect(result.current.state.draft.enhance).toBe(true);
   });
 
-  it('does not overwrite an items selector the user already typed', async () => {
+  it('keeps a typed items selector while still exposing the suggestion', async () => {
     const pendingSuggestion = Promise.withResolvers<Response>();
     mockStudioFetch(fetchMock, {
       suggest: () => pendingSuggestion.promise,
@@ -390,8 +403,9 @@ describe('useStudio', () => {
       pendingSuggestion.resolve(Response.json(suggestionBody(true, '.post')));
     });
 
-    await waitFor(() => expect(result.current.state.draft.enhance).toBe(true));
+    await waitFor(() => expect(result.current.suggestion?.itemsSelector).toBe('.post'));
     expect(result.current.state.draft.itemsSelector).toBe('article.mine');
+    expect(result.current.state.draft.enhance).toBe(false);
     expect(callsTo(fetchMock, '/feeds/suggest_selectors')).toHaveLength(1);
   });
 
@@ -425,7 +439,7 @@ describe('useStudio', () => {
     expect(live.sample.items[1]?.imageUrl).toBeUndefined();
   });
 
-  it('applies one capture suggestion onto the items selector', async () => {
+  it('applies one stored suggestion onto the items selector when accepted', async () => {
     mockStudioFetch(fetchMock, {
       suggest: () => Response.json(suggestionBody(true, '.post')),
       preview: () => Response.json(previewBody([], { quality_report: wireNull })),
@@ -434,7 +448,7 @@ describe('useStudio', () => {
     const { result } = renderHook(() =>
       useStudio({ url: pageUrl, token, validateDelayMs: 0, previewSettleMs: 60_000 })
     );
-    await waitFor(() => expect(result.current.state.phase).toBe('editing'));
+    await waitFor(() => expect(result.current.suggestion?.itemsSelector).toBe('.post'));
 
     act(() => {
       result.current.setItemsSelector('article.bad');
@@ -443,21 +457,12 @@ describe('useStudio', () => {
     expect(result.current.state.draft.itemsSelector).toBe('article.bad');
     expect(result.current.state.draft.enhance).toBe(false);
 
-    const suggestCountBeforeApply = callsTo(fetchMock, '/feeds/suggest_selectors').length;
     act(() => {
-      result.current.requestSuggestion();
+      result.current.acceptSuggestion();
     });
 
-    await waitFor(() => expect(result.current.state.draft.itemsSelector).toBe('.post'));
+    expect(result.current.state.draft.itemsSelector).toBe('.post');
     expect(result.current.state.draft.enhance).toBe(true);
-
-    const applyCall = callsTo(fetchMock, '/feeds/suggest_selectors')[suggestCountBeforeApply]?.[0];
-    expect(applyCall).toBeInstanceOf(Request);
-    if (!(applyCall instanceof Request)) return;
-    expect(JSON.parse(await applyCall.clone().text())).toEqual({
-      url: pageUrl,
-      items_selector: '',
-    });
   });
 
   it('fails closed when validate is unauthorized', async () => {
diff --git a/frontend/src/components/ConfigStudio.tsx b/frontend/src/components/ConfigStudio.tsx
index 62de00ef..4cb22c95 100644
--- a/frontend/src/components/ConfigStudio.tsx
+++ b/frontend/src/components/ConfigStudio.tsx
@@ -4,9 +4,9 @@ import type { RefinedSelectorsDocument } from '../api/generated/types.gen';
 import { COPY } from '../journey/copy';
 import { PreviewItem } from './PreviewItem';
 import { Notice } from './Notice';
-import { issuePlace, STUDIO_FIELDS, type StudioFieldId } from '../studio/selectorDraft';
+import { draftMatchesItemsSuggestion, issuePlace, STUDIO_FIELDS, type StudioFieldId } from '../studio/selectorDraft';
 import { canSaveStudio, studioIssues, useStudio, type StudioState } from '../studio/useStudio';
-import type { StudioIssue, StudioSampleItem } from '../studio/studioService';
+import type { StudioIssue, StudioSampleItem, StudioSuggestion } from '../studio/studioService';
 
 /** Settle delay before URL edits re-trigger suggest / validate / preview. */
 export const STUDIO_URL_SETTLE_MS = 400;
@@ -40,7 +40,7 @@ export function ConfigStudio(properties: ConfigStudioProperties) {
     token,
     live: isInline ? 'after-edit' : 'immediate',
   });
-  const { state } = studio;
+  const { state, suggestion } = studio;
   const issues = studioIssues(state);
   const [panel, setPanel] = useState<OpenPanel | undefined>(undefined);
   const [yamlOpen, setYamlOpen] = useState(false);
@@ -54,6 +54,8 @@ export function ConfigStudio(properties: ConfigStudioProperties) {
   const ready = state.live.status === 'ready' ? state.live.sample : undefined;
   const nativeFeedUrl = ready?.nativeFeedUrl;
   const isBusy = state.phase === 'validating' || state.phase === 'saving' || state.live.status === 'loading';
+  const showSuggestion =
+    suggestion !== undefined && !draftMatchesItemsSuggestion(state.draft, suggestion);
 
   useEffect(() => {
     setUrlDraft(url);
@@ -130,147 +132,146 @@ export function ConfigStudio(properties: ConfigStudioProperties) {
       />
     );
 
-  const controls = (
-    <>
-      <div class="layout-rail-reading layout-stack refine-controls">
-        {state.phase === 'failed' ? (
-          <Notice title={COPY.createFailedTitle} tone="error">
-            {state.message.trim() && state.message !== COPY.createFailedTitle ? (
-              <p>{state.message}</p>
-            ) : undefined}
-          </Notice>
-        ) : undefined}
+  const authoring = (
+    <div class="layout-rail-reading layout-stack refine-controls">
+      {state.phase === 'failed' ? (
+        <Notice title={COPY.createFailedTitle} tone="error">
+          {state.message.trim() && state.message !== COPY.createFailedTitle ? (
+            <p>{state.message}</p>
+          ) : undefined}
+        </Notice>
+      ) : undefined}
 
-        <label class="field-block" htmlFor="studio-items-selector">
-          <span class="ui-eyebrow">{COPY.itemsSelector}</span>
+      <label class="field-block" htmlFor="studio-items-selector">
+        <span class="ui-eyebrow">{COPY.itemsSelector}</span>
+        <input
+          id="studio-items-selector"
+          class="input input--mono input--lg"
+          value={state.draft.itemsSelector}
+          autoFocus={!isInline}
+          ref={itemsReference}
+          spellcheck={false}
+          onInput={(event) => studio.setItemsSelector(inputValue(event))}
+        />
+        <FieldErrors messages={messagesFor(issues, (issue) => issuePlace(issue.path).kind === 'items')} />
+      </label>
+
+      {showSuggestion && suggestion ? (
+        <SuggestionChip suggestion={suggestion} onAccept={studio.acceptSuggestion} />
+      ) : undefined}
+
+      <div class="refine-enhance">
+        <label class="refine-enhance__label" htmlFor="studio-enhance">
           <input
-            id="studio-items-selector"
-            class="input input--mono input--lg"
-            value={state.draft.itemsSelector}
-            autoFocus={!isInline}
-            ref={itemsReference}
-            spellcheck={false}
-            onInput={(event) => studio.setItemsSelector(inputValue(event))}
+            id="studio-enhance"
+            class="refine-check"
+            type="checkbox"
+            checked={state.draft.enhance}
+            onChange={(event) => studio.setEnhance(isInputChecked(event))}
           />
-          <FieldErrors messages={messagesFor(issues, (issue) => issuePlace(issue.path).kind === 'items')} />
+          <span class="refine-enhance__copy">
+            <span class="ui-eyebrow">{COPY.enhanceItems}</span>
+          </span>
         </label>
+        <FieldErrors messages={messagesFor(issues, (issue) => issuePlace(issue.path).kind === 'enhance')} />
+      </div>
 
-        <div class="refine-controls__actions">
-          <button type="button" class="btn btn--quiet" onClick={() => studio.requestSuggestion()}>
-            {COPY.applySuggestion}
-          </button>
-        </div>
-
-        <div class="refine-enhance">
-          <label class="refine-enhance__label" htmlFor="studio-enhance">
-            <input
-              id="studio-enhance"
-              class="refine-check"
-              type="checkbox"
-              checked={state.draft.enhance}
-              onChange={(event) => studio.setEnhance(isInputChecked(event))}
-            />
-            <span class="refine-enhance__copy">
-              <span class="ui-eyebrow">{COPY.enhanceItems}</span>
-            </span>
-          </label>
-          <FieldErrors messages={messagesFor(issues, (issue) => issuePlace(issue.path).kind === 'enhance')} />
-        </div>
-
-        {hiddenIssues.length > 0 ? (
-          <button type="button" class="btn btn--quiet btn--linkish" onClick={onHiddenIssues}>
-            {COPY.issueCount(hiddenIssues.length)}
-          </button>
-        ) : undefined}
+      {hiddenIssues.length > 0 ? (
+        <button type="button" class="btn btn--quiet btn--linkish" onClick={onHiddenIssues}>
+          {COPY.issueCount(hiddenIssues.length)}
+        </button>
+      ) : undefined}
 
-        {panel ? (
-          <FieldFixPanel
-            field={panel.field}
-            selector={state.draft.fields[panel.field].selector}
-            selectorMessages={fieldMessages(issues, panel.field)}
-            onSelector={(selector) => studio.setFieldSelector(panel.field, selector)}
-          />
-        ) : undefined}
+      {panel ? (
+        <FieldFixPanel
+          field={panel.field}
+          selector={state.draft.fields[panel.field].selector}
+          selectorMessages={fieldMessages(issues, panel.field)}
+          onSelector={(selector) => studio.setFieldSelector(panel.field, selector)}
+        />
+      ) : undefined}
 
-        {showUnmapped && unmappedIssues.length > 0 ? (
-          <Notice tone="error">
-            {unmappedIssues.map((issue) => (
-              <p key={issueKey(issue)}>{issue.message}</p>
-            ))}
-          </Notice>
-        ) : undefined}
+      {showUnmapped && unmappedIssues.length > 0 ? (
+        <Notice tone="error">
+          {unmappedIssues.map((issue) => (
+            <p key={issueKey(issue)}>{issue.message}</p>
+          ))}
+        </Notice>
+      ) : undefined}
 
-        <div class="ui-actions">
-          <button
-            type="button"
-            class="btn btn--primary"
-            disabled={!canSaveStudio(state)}
-            onClick={() => {
-              if (!flushUrlBeforeSave()) return;
-              void studio.save(onGenerate);
-            }}
-          >
-            {state.phase === 'saving' ? COPY.creating : COPY.saveAndGenerate}
-          </button>
-        </div>
+      <div class="ui-actions">
+        <button
+          type="button"
+          class="btn btn--primary"
+          disabled={!canSaveStudio(state)}
+          onClick={() => {
+            if (!flushUrlBeforeSave()) return;
+            void studio.save(onGenerate);
+          }}
+        >
+          {state.phase === 'saving' ? COPY.creating : COPY.saveAndGenerate}
+        </button>
       </div>
+    </div>
+  );
 
-      <div class="layout-rail-reading layout-stack layout-stack--tight refine-support">
-        <label class="field-block" htmlFor="studio-url">
-          <span class="ui-eyebrow">{COPY.urlLabel}</span>
-          <input
-            id="studio-url"
-            class="input input--mono"
-            type="url"
-            value={urlDraft}
-            spellcheck={false}
-            autoComplete="url"
-            onInput={(event) => setUrlDraft(inputValue(event))}
-            onBlur={onUrlBlur}
-          />
-        </label>
+  const support = (
+    <div class="layout-rail-reading layout-stack layout-stack--tight refine-support">
+      <label class="field-block" htmlFor="studio-url">
+        <span class="ui-eyebrow">{COPY.urlLabel}</span>
+        <input
+          id="studio-url"
+          class="input input--mono"
+          type="url"
+          value={urlDraft}
+          spellcheck={false}
+          autoComplete="url"
+          onInput={(event) => setUrlDraft(inputValue(event))}
+          onBlur={onUrlBlur}
+        />
+      </label>
 
-        {nativeFeedUrl ? (
-          <Notice title={COPY.nativeFeedTitle}>
-            <a class="input--mono" href={nativeFeedUrl} target="_blank" rel="noopener noreferrer">
-              {nativeFeedUrl}
-            </a>
-          </Notice>
-        ) : undefined}
+      {nativeFeedUrl ? (
+        <Notice title={COPY.nativeFeedTitle}>
+          <a class="input--mono" href={nativeFeedUrl} target="_blank" rel="noopener noreferrer">
+            {nativeFeedUrl}
+          </a>
+        </Notice>
+      ) : undefined}
 
-        <div class="layout-stack layout-stack--tight">
-          <button
-            type="button"
-            class="btn btn--quiet btn--linkish"
-            onClick={() => setYamlOpen((open) => !open)}
-          >
-            {COPY.viewAsYaml}
-          </button>
-          {yamlOpen ? (
-            <>
-              <pre class="refine-yaml input input--mono">{state.yaml}</pre>
-              <button
-                type="button"
-                class="btn btn--quiet btn--linkish"
-                onClick={() => {
-                  void copyYaml(state.yaml, setCopied, copyResetReference);
-                }}
-              >
-                {copied ? COPY.copied : COPY.copy}
-              </button>
-              <p class="field-help">{COPY.yamlFragmentCaption}</p>
-            </>
-          ) : undefined}
-        </div>
+      <div class="layout-stack layout-stack--tight">
+        <button
+          type="button"
+          class="btn btn--quiet btn--linkish"
+          onClick={() => setYamlOpen((open) => !open)}
+        >
+          {COPY.viewAsYaml}
+        </button>
+        {yamlOpen ? (
+          <>
+            <pre class="refine-yaml input input--mono">{state.yaml}</pre>
+            <button
+              type="button"
+              class="btn btn--quiet btn--linkish"
+              onClick={() => {
+                void copyYaml(state.yaml, setCopied, copyResetReference);
+              }}
+            >
+              {copied ? COPY.copied : COPY.copy}
+            </button>
+            <p class="field-help">{COPY.yamlFragmentCaption}</p>
+          </>
+        ) : undefined}
       </div>
-    </>
+    </div>
   );
 
   if (isInline) {
     return (
       <div class="layout-stack" aria-busy={isBusy}>
+        {authoring}
         {meadow}
-        {controls}
+        {support}
       </div>
     );
   }
@@ -287,12 +288,33 @@ export function ConfigStudio(properties: ConfigStudioProperties) {
           {COPY.refineSelectors}
         </h1>
       </header>
+      {authoring}
       {meadow}
-      {controls}
+      {support}
     </section>
   );
 }
 
+function SuggestionChip({
+  suggestion,
+  onAccept,
+}: {
+  readonly suggestion: StudioSuggestion;
+  readonly onAccept: () => void;
+}) {
+  return (
+    <div class="refine-suggestion" role="group" aria-label={COPY.suggestedSelectorLabel}>
+      <p class="refine-suggestion__text">
+        <span>{COPY.suggestedSelectorLabel}</span>{' '}
+        <code class="input--mono refine-suggestion__selector">{suggestion.itemsSelector}</code>
+      </p>
+      <button type="button" class="btn btn--quiet" onClick={onAccept}>
+        {COPY.useSuggestion}
+      </button>
+    </div>
+  );
+}
+
 function PreviewPane({
   state,
   token,
diff --git a/frontend/src/journey/copy.ts b/frontend/src/journey/copy.ts
index 60db7831..d564de03 100644
--- a/frontend/src/journey/copy.ts
+++ b/frontend/src/journey/copy.ts
@@ -70,7 +70,8 @@ export const COPY = {
   previewRegion: 'Feed preview',
   itemsSelector: 'Items selector',
   enhanceItems: 'Enhance items',
-  applySuggestion: 'Use determined selector',
+  suggestedSelectorLabel: 'Suggested:',
+  useSuggestion: 'Use',
   saveAndGenerate: 'Save and generate feed',
   viewAsYaml: 'View as YAML',
   yamlFragmentCaption: 'Selectors fragment — not a feeds.yml config',
diff --git a/frontend/src/studio/selectorDraft.ts b/frontend/src/studio/selectorDraft.ts
index a120ab3f..2496a4fc 100644
--- a/frontend/src/studio/selectorDraft.ts
+++ b/frontend/src/studio/selectorDraft.ts
@@ -100,6 +100,14 @@ export function applyItemsSuggestion(
   return { ...draft, itemsSelector, enhance: isEnhanced };
 }
 
+/** True when the authored draft already matches the server suggestion (chip has nothing to apply). */
+export function draftMatchesItemsSuggestion(
+  draft: StudioDraft,
+  suggestion: { readonly itemsSelector: string; readonly enhance: boolean }
+): boolean {
+  return draft.itemsSelector === suggestion.itemsSelector && draft.enhance === suggestion.enhance;
+}
+
 export function issuePlace(path: readonly string[]): IssuePlace {
   const scope = selectorScope(path);
   const head = scope[0];
diff --git a/frontend/src/studio/useStudio.ts b/frontend/src/studio/useStudio.ts
index cf55282c..9b7a2c0a 100644
--- a/frontend/src/studio/useStudio.ts
+++ b/frontend/src/studio/useStudio.ts
@@ -50,7 +50,7 @@ interface UseStudioOptions {
   readonly token: string;
   readonly validateDelayMs?: number;
   readonly previewSettleMs?: number;
-  /** `after-edit` skips mount-time suggest and live preview so a result meadow can stay single. */
+  /** `after-edit` skips mount-time live preview so a result meadow can stay single. */
   readonly live?: 'immediate' | 'after-edit';
 }
 
@@ -68,6 +68,7 @@ export function useStudio({
     validated: false,
     live: { status: 'idle' },
   });
+  const [suggestion, setSuggestion] = useState<StudioSuggestion | undefined>(undefined);
   const [documentRevision, setDocumentRevision] = useState(0);
 
   const stateReference = useRef(state);
@@ -99,11 +100,9 @@ export function useStudio({
   }, [documentRevision, live, token, url, validateDelayMs]);
 
   useEffect(() => {
-    if (live === 'after-edit' && url === initialUrlReference.current) return;
-
     const requestId = ++suggestRequestReference.current;
     const controller = new AbortController();
-    void loadEnhanceEvidence(requestId, controller.signal);
+    void loadSuggestion(requestId, controller.signal);
 
     return () => {
       controller.abort();
@@ -117,20 +116,11 @@ export function useStudio({
     };
   }, []);
 
-  async function loadEnhanceEvidence(requestId: number, signal: AbortSignal) {
+  async function loadSuggestion(requestId: number, signal: AbortSignal) {
     try {
       const evidence = await suggestStudioSelectors(token, url, '', signal);
       if (signal.aborted || suggestRequestReference.current !== requestId) return;
-      const next = prefillFromSuggestion(
-        stateReference.current.draft,
-        evidence,
-        itemsTouchedReference.current,
-        enhanceTouchedReference.current
-      );
-      if (next === stateReference.current.draft) return;
-      editSelectors((draft) =>
-        prefillFromSuggestion(draft, evidence, itemsTouchedReference.current, enhanceTouchedReference.current)
-      );
+      setSuggestion(evidence);
     } catch (error) {
       if (isAbortError(error) || signal.aborted || suggestRequestReference.current !== requestId) return;
     }
@@ -251,11 +241,7 @@ export function useStudio({
     try {
       const nextSuggestion = await suggestStudioSelectors(token, url, '');
       if (suggestRequestReference.current !== requestId) return;
-      itemsTouchedReference.current = true;
-      enhanceTouchedReference.current = true;
-      editSelectors((draft) =>
-        applyItemsSuggestion(draft, nextSuggestion.itemsSelector, nextSuggestion.enhance)
-      );
+      setSuggestion(nextSuggestion);
     } catch (error) {
       if (isAbortError(error) || suggestRequestReference.current !== requestId) return;
       setState((previous) => ({
@@ -268,6 +254,16 @@ export function useStudio({
     }
   }
 
+  function acceptSuggestion() {
+    const current = suggestion;
+    if (!current) return;
+    itemsTouchedReference.current = true;
+    enhanceTouchedReference.current = true;
+    editSelectors((draft) =>
+      applyItemsSuggestion(draft, current.itemsSelector, current.enhance)
+    );
+  }
+
   function retryPreview() {
     const current = stateReference.current;
     if (!(current.phase === 'editing' && current.validated)) return;
@@ -297,9 +293,11 @@ export function useStudio({
 
   return {
     state,
+    suggestion,
     setItemsSelector,
     setEnhance,
     setFieldSelector,
+    acceptSuggestion,
     requestSuggestion: () => {
       void requestSuggestion();
     },
@@ -316,19 +314,6 @@ export function canSaveStudio(state: StudioState): boolean {
   return state.phase === 'editing' && state.validated;
 }
 
-function prefillFromSuggestion(
-  draft: StudioDraft,
-  suggestion: StudioSuggestion,
-  isItemsTouched: boolean,
-  isEnhanceTouched: boolean
-): StudioDraft {
-  const canFillItems = !isItemsTouched && suggestion.itemsSelector.length > 0;
-  const itemsSelector = (canFillItems ? suggestion : draft).itemsSelector;
-  const enhance = (isEnhanceTouched ? draft : suggestion).enhance;
-  if (itemsSelector === draft.itemsSelector && enhance === draft.enhance) return draft;
-  return applyItemsSuggestion(draft, itemsSelector, enhance);
-}
-
 function adoptServerDraft(sent: StudioDraft, incoming: StudioDraft): StudioDraft {
   return {
     ...sent,
diff --git a/frontend/src/styles/main.css b/frontend/src/styles/main.css
index 8393f84d..cfe8b7a3 100644
--- a/frontend/src/styles/main.css
+++ b/frontend/src/styles/main.css
@@ -581,6 +581,22 @@
   justify-content: flex-start;
 }
 
+.refine-suggestion {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--space-3);
+}
+
+.refine-suggestion__text {
+  margin: 0;
+  min-width: 0;
+}
+
+.refine-suggestion__selector {
+  word-break: break-all;
+}
+
 .refine-enhance {
   display: flex;
   flex-direction: column;

From 4d0e0378cff13643070103ff35cd0ad9c9e97fdd Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 20 Sep 2026 20:31:41 +0200
Subject: [PATCH 062/108] docs(journey): gate result refinement behind an
 explicit action

---
 CONTEXT.md                                    |  2 +-
 docs/design-system.md                         |  6 ++--
 docs/personas.md                              |  2 +-
 frontend/e2e/smoke.spec.ts                    | 33 ++++++++++++++++---
 frontend/src/__tests__/ResultDisplay.test.tsx |  2 +-
 frontend/src/components/ConfigStudio.tsx      | 13 +++++---
 frontend/src/components/ResultDisplay.tsx     |  2 +-
 frontend/src/studio/selectorDraft.ts          |  2 +-
 frontend/src/studio/useStudio.ts              |  4 +--
 9 files changed, 46 insertions(+), 20 deletions(-)

diff --git a/CONTEXT.md b/CONTEXT.md
index 3efee2e5..82f68279 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -29,7 +29,7 @@ On create, `findCatalogEntries` matches the typed query against the catalog (URL
 Visiting create (including hashbang `#!/…` → `#/…`) bumps `createEntryKey` so the create surface remounts. Remount alone does not auto-submit; auto-submit requires `prefillUrl`.
 
 ### Config Studio
-Selector refinement for a token holder when studio is enabled. A successful result owns that refinement inline on `#/result/:token` (one meadow; live studio output replaces the result preview). `#/refine` is only extraction-empty recovery when no result exists. Memory-bound to the in-memory page URL (no token in the route). The visual builder and YAML are one document; only `studioService` unwraps the studio envelope. Save posts refined selectors through Creation IO and stays on the result view.
+Selector refinement for a token holder when studio is enabled. On a successful result, refinement is available on demand behind demoted **Refine selectors** on `#/result/:token` (collapsed by default; one meadow; live studio output replaces the result preview when expanded). `#/refine` is only extraction-empty recovery when no result exists. Memory-bound to the in-memory page URL (no token in the route). The visual builder and YAML are one document; only `studioService` unwraps the studio envelope. A server suggestion is held separately from the authored draft until the user accepts it. Save posts refined selectors through Creation IO and stays on the result view.
 
 ### Refined Selectors
 The allowlisted `selectors` document a token holder may attach on feed creation. Signed into the feed token and resolved on later serves. Not a full config: channel, headers, and strategy stay denied.
diff --git a/docs/design-system.md b/docs/design-system.md
index 84ae389d..15013fbe 100644
--- a/docs/design-system.md
+++ b/docs/design-system.md
@@ -40,9 +40,9 @@ If a page looks like it came from a different product, the change is wrong even
 
 - **Create:** URL field is the task. Visiting `#/create` or `#!/create` remounts create; hashbang aliases canonicalize to `#/create`. Bare create does not auto-submit. When the typed query finds catalog entries (URL equivalence or text substring), show matching feeds as a subordinate list under the field — never a second primary task or in-app catalog browser. On an empty Create URL, up to three Feed Directory starters may appear as subordinate chrome (lean: `.ui-eyebrow` + list + demoted `utility-link` escape under the list when creation is enabled; Notice when creation is disabled). Escape and utility-strip share **Browse Feed Directory (N)** (`catalogEntries.length`); hide starters and the under-list escape while typing, when find has hits, or while creating.
 - **Token gate:** a native `<dialog>` over the still-mounted, inert URL task (one interactive task). Auth copy is in-field (`tokenError`); ActionFeedback stays on create. Access Token persists until Logout with no storage UI.
-- **Result:** primary CTA is **Copy feed URL**, and it takes initial focus. Open feed / JSON / feed-reader are demoted secondary actions and stay available while preview loads. Preview is one meadow and non-blocking confirmation only. Guest results stay compact: at most 5 items, no images, no selector controls. An authenticated, studio-enabled result keeps that same frame and adds selector controls below the meadow. Selector edits replace the meadow with live studio output; they do not add a second list. **Save and generate feed** is the only primary action inside those controls. Member previews may show up to 10 items and safe HTTP(S) images.
+- **Result:** primary CTA is **Copy feed URL**, and it takes initial focus. Open feed / JSON / feed-reader are demoted secondary actions and stay available while preview loads. Preview is one meadow and non-blocking confirmation only. Guest results stay compact: at most 5 items, no images, no selector controls. An authenticated, studio-enabled result keeps that same frame: a demoted **Refine selectors** action in `ui-actions` (collapsed by default). Opening it mounts selector controls **above** the meadow; closing it returns to the static meadow without discarding the in-memory draft. Studio validate/preview/suggest do not run until the panel opens. Selector edits replace the meadow with live studio output; they do not add a second list. **Save and generate feed** is the only primary action inside those controls. Member previews may show up to 10 items and safe HTTP(S) images.
 - **Empty extraction:** **Refine selectors** is one quiet action beside Try again when the extraction is empty, studio is enabled, and an access token is present. It is not offered for other create errors, guests, or a studio-off instance.
-- **Refine:** `#/refine` is memory-bound extraction-empty recovery for an authenticated studio (see [personas.md](personas.md) J2). No token in the route. A successful in-memory result replaces `#/refine` with `#/result/:token`; refinement of that feed stays on the result. Standalone recovery uses the same frame as Result: a `result-shell` / `layout-stack` rail — never a mega-card bisected by the fixed footer, never a two-column paddock. First viewport leads with the live preview meadow (`.ui-item-list`) after validation, then compact controls: items selector, left-aligned **Use determined selector**, a large Enhance hit target, and **Save and generate feed** as the only `btn--primary` in `ui-actions`. URL, native-feed Notice, and View as YAML are demoted support below the controls. Changing the URL re-suggests and re-previews without leaving the current surface or running catalog find; empty URL recovers onto remounted `#/create`. Prefill: an empty items selector is filled once from suggestion while untouched, and Enhance follows that suggestion until the user changes either. **Use determined selector** re-fetches capture with no items hint and overwrites items + Enhance. Wire is the typed closed selectors document (no strip/trim/affix cleanup UI). Fix a field opens one selector panel **in the stack** for Title, Link, or Published date. View as YAML is read-only and captioned as a selectors fragment — not a feeds.yml. Save-failure Notices use wire `Decision#message` — never create-journey copy. When studio is disabled or the caller has no token, Refine actions stay hidden and `#/refine` bounces to create. Focus on standalone recovery is the items selector; a successful Result keeps focus on Copy.
+- **Refine:** `#/refine` is memory-bound extraction-empty recovery for an authenticated studio (see [personas.md](personas.md) J2). No token in the route. A successful in-memory result replaces `#/refine` with `#/result/:token`; refinement of that feed stays on the result behind the same demoted **Refine selectors** gate. Standalone recovery uses the same frame as an expanded Result: a `result-shell` / `layout-stack` rail — never a mega-card bisected by the fixed footer, never a two-column paddock. First viewport leads with compact controls (items selector, visible **Suggested:** chip + **Use**, a large Enhance hit target, and **Save and generate feed** as the only `btn--primary` in `ui-actions`), then the live preview meadow (`.ui-item-list`) after validation. URL, native-feed Notice, and View as YAML are demoted support below the meadow. Changing the URL re-suggests and re-previews without leaving the current surface or running catalog find; empty URL recovers onto remounted `#/create`. Suggestion is held separately from the authored draft and shown as a comparable chip; **Use** applies items + Enhance only when the user accepts. Wire is the typed closed selectors document (no strip/trim/affix cleanup UI). Fix a field opens one selector panel **in the stack** for Title, Link, or Published date. View as YAML is read-only and captioned as a selectors fragment — not a feeds.yml. Save-failure Notices use wire `Decision#message` — never create-journey copy. When studio is disabled or the caller has no token, Refine actions stay hidden and `#/refine` bounces to create. Focus on standalone recovery is the items selector; a successful Result keeps focus on Copy whether Refine is open or closed.
 - **Unmatched result:** `#/result/:token` is valid only with a matching in-memory result. Missing or mismatched tokens recover onto remounted `#/create` (no API rehydrate, no failure chrome, no durable shareable result page).
 - **Status eyebrow:** one vocabulary (`Feed ready`) on the result header; preview progress lives in the preview section.
 - **Focus:** create autofocuses the URL field; token autofocuses the token field; result focuses the Copy control; standalone extraction-empty refine focuses the items selector.
@@ -55,7 +55,7 @@ If a page looks like it came from a different product, the change is wrong even
 | Output | **Feed URL** |
 | Create | **Create feed** / **Creating feed** |
 | Result | **Feed ready** / **Copy feed URL** |
-| Refine | **Refine selectors** / **Use determined selector** / **Save and generate feed** / **View as YAML** |
+| Refine | **Refine selectors** / **Suggested:** / **Use** / **Save and generate feed** / **View as YAML** |
 | Retry | **Try again** (button only) |
 | Preview | **Checking preview** / **Check again** |
 | Catalog | **Feed Directory** |
diff --git a/docs/personas.md b/docs/personas.md
index 26176afe..c9f72117 100644
--- a/docs/personas.md
+++ b/docs/personas.md
@@ -20,7 +20,7 @@ Bookmarklet is a **Sam on-ramp**, not a fifth persona.
 - **Job:** Paste a listing URL, get a feed URL, subscribe in a reader.
 - **Owning surface:** html2rss-web SPA.
 - **Golden path:** Create → token (if needed) → Result → **Copy feed URL**.
-- **Recovery only:** wrong list or missing Title/Link/Published (J3) and a wrong listing URL (J3b) stay on Result for a token holder when studio is enabled. `#/refine` is only **J2** (empty extraction) when no successful result exists. It is not an authoring product.
+- **Recovery only:** wrong list or missing Title/Link/Published (J3) and a wrong listing URL (J3b) stay on Result for a token holder when studio is enabled — behind the same demoted **Refine selectors** quiet action used for **J2** (empty extraction), collapsed by default. `#/refine` is only **J2** when no successful result exists. It is not an authoring product.
 - **Non-goal:** Learning YAML, MCP, or directory contribution through the SPA.
 
 ## Alex — operator
diff --git a/frontend/e2e/smoke.spec.ts b/frontend/e2e/smoke.spec.ts
index e5953d92..821ea60e 100644
--- a/frontend/e2e/smoke.spec.ts
+++ b/frontend/e2e/smoke.spec.ts
@@ -183,8 +183,10 @@ test.describe('frontend smoke', () => {
     await expect(page.getByRole('link', { name: COPY.openJsonFeed })).toBeVisible();
     await expect(page.getByRole('link', { name: COPY.openInFeedReader })).toBeVisible();
     await expect(page.getByRole('button', { name: COPY.createAnother })).toBeVisible();
-    await expect(page.getByRole('button', { name: COPY.refineSelectors })).toHaveCount(0);
-    await expect(page.getByLabel(COPY.itemsSelector)).toBeVisible();
+    const refine = page.getByRole('button', { name: COPY.refineSelectors });
+    await expect(refine).toBeVisible();
+    await expect(refine).toHaveAttribute('aria-expanded', 'false');
+    await expect(page.getByLabel(COPY.itemsSelector)).toHaveCount(0);
     await expect(page.locator('.ui-item-list')).toHaveCount(1);
     await expect(page.getByText('Sample preview item')).toBeVisible();
     await expect(page.getByText('Current preview fetch includes rendered content.')).toBeVisible();
@@ -208,23 +210,37 @@ test.describe('frontend smoke', () => {
   });
 
   test('refines a result in place and generates the feed without a live scrape', async ({ page }) => {
+    const validateRequests: Request[] = [];
+    const previewRequests: Request[] = [];
+    collectPosts(page, API_VALIDATE, validateRequests);
+    collectPosts(page, API_STUDIO_PREVIEW, previewRequests);
+
     await createReadyResult(page);
 
     await expect(page).toHaveURL(/\/#\/result\/generated-token$/);
     await expect(page.locator('.result-shell')).toHaveAttribute('data-state', 'result');
     await expect(page.getByRole('button', { name: COPY.copyFeedUrl })).toBeFocused();
-    await expect(page.getByRole('button', { name: COPY.refineSelectors })).toHaveCount(0);
+    const refine = page.getByRole('button', { name: COPY.refineSelectors });
+    await expect(refine).toBeVisible();
+    await expect(refine).toHaveAttribute('aria-expanded', 'false');
+    await expect(page.getByLabel(COPY.itemsSelector)).toHaveCount(0);
     await expect(page.locator('.ui-card')).toHaveCount(0);
+    expect(validateRequests).toHaveLength(0);
+    expect(previewRequests).toHaveLength(0);
+
+    await refine.click();
+    await expect(refine).toHaveAttribute('aria-expanded', 'true');
 
     const items = page.getByLabel(COPY.itemsSelector);
     await expect(items).toBeVisible();
+    await expect.poll(() => validateRequests.length, { timeout: 5000 }).toBeGreaterThan(0);
     await items.fill('article');
     await expect(page.getByText('Refine meadow item')).toBeVisible();
     await expect(page.locator('.ui-item-list')).toHaveCount(1);
     const meadow = page.getByLabel(COPY.previewRegion, { exact: true });
     const meadowBox = await meadow.boundingBox();
     const itemsBox = await items.boundingBox();
-    expect(meadowBox && itemsBox && meadowBox.y < itemsBox.y).toBe(true);
+    expect(itemsBox && meadowBox && itemsBox.y < meadowBox.y).toBe(true);
     const enhanceBox = await page.locator('.refine-enhance__label').boundingBox();
     expect(enhanceBox && enhanceBox.height >= 40).toBe(true);
     await expect(page.getByRole('button', { name: COPY.fieldFound(COPY.fieldTitle) })).toBeVisible();
@@ -255,6 +271,12 @@ test.describe('frontend smoke', () => {
     await createReadyResult(page);
     await expect(page).toHaveURL(/\/#\/result\/generated-token$/);
     await expect(page.locator('.ui-item-list')).toHaveCount(0);
+    expect(suggestRequests).toHaveLength(0);
+    expect(previewRequests).toHaveLength(0);
+
+    await page.getByRole('button', { name: COPY.refineSelectors }).click();
+    await expect(page.getByLabel(COPY.itemsSelector)).toBeVisible();
+    await expect.poll(() => suggestRequests.length, { timeout: 5000 }).toBeGreaterThan(0);
 
     const suggestBeforeEdit = suggestRequests.length;
     const previewBeforeEdit = previewRequests.length;
@@ -294,7 +316,8 @@ test.describe('frontend smoke', () => {
     await expect(page).toHaveURL(/\/#\/result\/generated-token$/);
     await expect(page.locator('.result-shell')).toHaveAttribute('data-state', 'result');
     await expect(page.getByRole('heading', { name: COPY.refineSelectors })).toHaveCount(0);
-    await expect(page.getByLabel(COPY.itemsSelector)).toBeVisible();
+    await expect(page.getByRole('button', { name: COPY.refineSelectors })).toBeVisible();
+    await expect(page.getByLabel(COPY.itemsSelector)).toHaveCount(0);
   });
 
   test('hides refine when studio is disabled and bounces forced refine onto create', async ({ page }) => {
diff --git a/frontend/src/__tests__/ResultDisplay.test.tsx b/frontend/src/__tests__/ResultDisplay.test.tsx
index 0c7e1936..d66097bc 100644
--- a/frontend/src/__tests__/ResultDisplay.test.tsx
+++ b/frontend/src/__tests__/ResultDisplay.test.tsx
@@ -303,7 +303,7 @@ describe('ResultDisplay', () => {
 
     fireEvent.click(refine);
     expect(refine).toHaveAttribute('aria-expanded', 'false');
-    const collapsedInput = document.getElementById('studio-items-selector');
+    const collapsedInput = document.querySelector('#studio-items-selector');
     expect(collapsedInput).not.toBeNull();
     expect(collapsedInput).not.toBeVisible();
     expect(document.querySelectorAll('.ui-item-list')).toHaveLength(1);
diff --git a/frontend/src/components/ConfigStudio.tsx b/frontend/src/components/ConfigStudio.tsx
index 4cb22c95..f2aa1399 100644
--- a/frontend/src/components/ConfigStudio.tsx
+++ b/frontend/src/components/ConfigStudio.tsx
@@ -4,7 +4,12 @@ import type { RefinedSelectorsDocument } from '../api/generated/types.gen';
 import { COPY } from '../journey/copy';
 import { PreviewItem } from './PreviewItem';
 import { Notice } from './Notice';
-import { draftMatchesItemsSuggestion, issuePlace, STUDIO_FIELDS, type StudioFieldId } from '../studio/selectorDraft';
+import {
+  isDraftMatchingItemsSuggestion,
+  issuePlace,
+  STUDIO_FIELDS,
+  type StudioFieldId,
+} from '../studio/selectorDraft';
 import { canSaveStudio, studioIssues, useStudio, type StudioState } from '../studio/useStudio';
 import type { StudioIssue, StudioSampleItem, StudioSuggestion } from '../studio/studioService';
 
@@ -54,8 +59,8 @@ export function ConfigStudio(properties: ConfigStudioProperties) {
   const ready = state.live.status === 'ready' ? state.live.sample : undefined;
   const nativeFeedUrl = ready?.nativeFeedUrl;
   const isBusy = state.phase === 'validating' || state.phase === 'saving' || state.live.status === 'loading';
-  const showSuggestion =
-    suggestion !== undefined && !draftMatchesItemsSuggestion(state.draft, suggestion);
+  const isShowSuggestion =
+    suggestion !== undefined && !isDraftMatchingItemsSuggestion(state.draft, suggestion);
 
   useEffect(() => {
     setUrlDraft(url);
@@ -156,7 +161,7 @@ export function ConfigStudio(properties: ConfigStudioProperties) {
         <FieldErrors messages={messagesFor(issues, (issue) => issuePlace(issue.path).kind === 'items')} />
       </label>
 
-      {showSuggestion && suggestion ? (
+      {isShowSuggestion && suggestion ? (
         <SuggestionChip suggestion={suggestion} onAccept={studio.acceptSuggestion} />
       ) : undefined}
 
diff --git a/frontend/src/components/ResultDisplay.tsx b/frontend/src/components/ResultDisplay.tsx
index 478bf3bb..42af606f 100644
--- a/frontend/src/components/ResultDisplay.tsx
+++ b/frontend/src/components/ResultDisplay.tsx
@@ -148,7 +148,7 @@ export function ResultDisplay({
               onUrlChange={studio.onUrlChange}
               onUrlCleared={studio.onUrlCleared}
               onGenerate={studio.onGenerate}
-              fallback={refineOpen ? meadow : null}
+              fallback={refineOpen ? meadow : undefined}
             />
           </div>
           {!refineOpen && meadow}
diff --git a/frontend/src/studio/selectorDraft.ts b/frontend/src/studio/selectorDraft.ts
index 2496a4fc..2ec6154f 100644
--- a/frontend/src/studio/selectorDraft.ts
+++ b/frontend/src/studio/selectorDraft.ts
@@ -101,7 +101,7 @@ export function applyItemsSuggestion(
 }
 
 /** True when the authored draft already matches the server suggestion (chip has nothing to apply). */
-export function draftMatchesItemsSuggestion(
+export function isDraftMatchingItemsSuggestion(
   draft: StudioDraft,
   suggestion: { readonly itemsSelector: string; readonly enhance: boolean }
 ): boolean {
diff --git a/frontend/src/studio/useStudio.ts b/frontend/src/studio/useStudio.ts
index 9b7a2c0a..188c0b87 100644
--- a/frontend/src/studio/useStudio.ts
+++ b/frontend/src/studio/useStudio.ts
@@ -259,9 +259,7 @@ export function useStudio({
     if (!current) return;
     itemsTouchedReference.current = true;
     enhanceTouchedReference.current = true;
-    editSelectors((draft) =>
-      applyItemsSuggestion(draft, current.itemsSelector, current.enhance)
-    );
+    editSelectors((draft) => applyItemsSuggestion(draft, current.itemsSelector, current.enhance));
   }
 
   function retryPreview() {

From 6dbd7a654030e084e0eb643a7e88b85128f7a48b Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Sun, 20 Sep 2026 20:37:01 +0200
Subject: [PATCH 063/108] test(studio): require suggestion accept before save
 asserts article

Default MSW validate now echoes request selectors so contract paths cannot
pass article from a silent overwrite without clicking Use.
---
 frontend/src/__tests__/App.contract.test.tsx |  8 ++++-
 frontend/src/__tests__/ConfigStudio.test.tsx | 26 +++++++++-----
 frontend/src/__tests__/mocks/apiFixtures.ts  | 37 ++++++++++++++++----
 frontend/src/__tests__/mocks/server.ts       | 12 +++----
 4 files changed, 60 insertions(+), 23 deletions(-)

diff --git a/frontend/src/__tests__/App.contract.test.tsx b/frontend/src/__tests__/App.contract.test.tsx
index d6625940..1f7ee00e 100644
--- a/frontend/src/__tests__/App.contract.test.tsx
+++ b/frontend/src/__tests__/App.contract.test.tsx
@@ -223,9 +223,15 @@ describe('App contract', () => {
 
     fireEvent.click(screen.getByRole('button', { name: COPY.refineSelectors }));
     const itemsSelector = await screen.findByLabelText(COPY.itemsSelector);
+    await waitFor(() => {
+      expect(itemsSelector).toHaveValue('a[href]');
+    });
+    const useSuggestion = await screen.findByRole('button', { name: COPY.useSuggestion });
+    fireEvent.click(useSuggestion);
     await waitFor(() => {
       expect(itemsSelector).toHaveValue('article');
     });
+    expect(screen.queryByRole('button', { name: COPY.useSuggestion })).not.toBeInTheDocument();
     const save = screen.getByRole('button', { name: COPY.saveAndGenerate });
     await waitFor(() => expect(save).toBeEnabled());
     expect(document.querySelectorAll('.ui-item-list')).toHaveLength(1);
@@ -237,7 +243,7 @@ describe('App contract', () => {
     });
     expect(bodies[1]).toMatchObject({
       url: 'https://example.com/articles',
-      selectors: { items: { selector: 'article' } },
+      selectors: { items: { selector: 'article', enhance: true } },
     });
     await screen.findByText(COPY.feedReady);
     fetchSpy.mockRestore();
diff --git a/frontend/src/__tests__/ConfigStudio.test.tsx b/frontend/src/__tests__/ConfigStudio.test.tsx
index 95d7b86d..0606b3c0 100644
--- a/frontend/src/__tests__/ConfigStudio.test.tsx
+++ b/frontend/src/__tests__/ConfigStudio.test.tsx
@@ -3,6 +3,11 @@ import { render, screen, fireEvent, waitFor, act } from '@testing-library/preact
 import { http, HttpResponse } from 'msw';
 import type { RefinedSelectorsDocument } from '../api/generated/types.gen';
 import { server } from './mocks/server';
+import {
+  selectorsFromValidateRequest,
+  validateSuccessBody,
+  validateYamlForSelectors,
+} from './mocks/apiFixtures';
 import { ConfigStudio, STUDIO_URL_SETTLE_MS } from '../components/ConfigStudio';
 import { COPY } from '../journey/copy';
 
@@ -68,12 +73,8 @@ const previewWithImage = () =>
 function echoValidate() {
   server.use(
     http.post('/api/v1/feeds/validate', async ({ request }) => {
-      const body: unknown = await request.json();
-      const selectors =
-        typeof body === 'object' && body && 'selectors' in body
-          ? body.selectors
-          : { items: { selector: 'article', enhance: false } };
-      return HttpResponse.json(validateEnvelope(selectors));
+      const selectors = selectorsFromValidateRequest(await request.json());
+      return HttpResponse.json(validateSuccessBody(selectors, validateYamlForSelectors(selectors)));
     })
   );
 }
@@ -140,9 +141,11 @@ describe('ConfigStudio', () => {
     expect(screen.queryByText(/Cleanup/i)).not.toBeInTheDocument();
     expect(screen.queryByText(/Strip HTML/i)).not.toBeInTheDocument();
     await waitFor(() => expect(items).toHaveFocus());
-    await waitFor(() => expect(items).toHaveValue('article'));
+    await waitFor(() => expect(items).toHaveValue('a[href]'));
     expect(screen.getByLabelText(COPY.enhanceItems)).toBeInTheDocument();
-    expect(screen.queryByRole('button', { name: COPY.useSuggestion })).toBeInTheDocument();
+    await waitFor(() =>
+      expect(screen.getByRole('button', { name: COPY.useSuggestion })).toBeInTheDocument()
+    );
     expect(screen.getByRole('button', { name: COPY.fieldMissing(COPY.fieldTitle) })).toBeInTheDocument();
     expect(screen.getByRole('button', { name: COPY.fieldMissing(COPY.fieldLink) })).toBeInTheDocument();
     expect(screen.getByRole('button', { name: COPY.fieldMissing(COPY.fieldPublished) })).toBeInTheDocument();
@@ -365,6 +368,8 @@ describe('ConfigStudio', () => {
 
   it('reveals read-only yaml captioned as a selectors fragment', async () => {
     renderStudio();
+    await waitFor(() => expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('a[href]'));
+    fireEvent.click(await screen.findByRole('button', { name: COPY.useSuggestion }));
     await waitFor(() => expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('article'));
 
     fireEvent.click(screen.getByRole('button', { name: COPY.viewAsYaml }));
@@ -379,10 +384,13 @@ describe('ConfigStudio', () => {
     const save = screen.getByRole('button', { name: COPY.saveAndGenerate });
     expect(save).toBeDisabled();
     await waitFor(() => expect(save).toBeEnabled());
+    fireEvent.click(await screen.findByRole('button', { name: COPY.useSuggestion }));
+    await waitFor(() => expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('article'));
+    await waitFor(() => expect(save).toBeEnabled());
 
     fireEvent.click(save);
 
     await waitFor(() => expect(onGenerate).toHaveBeenCalled());
-    expect(onGenerate.mock.calls[0]?.[0]).toEqual({ items: { selector: 'article' } });
+    expect(onGenerate.mock.calls[0]?.[0]).toEqual({ items: { selector: 'article', enhance: true } });
   });
 });
diff --git a/frontend/src/__tests__/mocks/apiFixtures.ts b/frontend/src/__tests__/mocks/apiFixtures.ts
index a72d26a6..796f0c97 100644
--- a/frontend/src/__tests__/mocks/apiFixtures.ts
+++ b/frontend/src/__tests__/mocks/apiFixtures.ts
@@ -101,16 +101,41 @@ export function buildStructuredErrorResponse(overrides: StructuredErrorOverrides
   };
 }
 
-export function validateSuccessBody(
-  selectors?: unknown,
-  yaml = 'selectors:\n  items:\n    selector: article\n'
-) {
+/** Prefer request selectors so validate does not invent an `article` items selector. */
+export function selectorsFromValidateRequest(body: unknown): unknown {
+  if (typeof body === 'object' && body && 'selectors' in body && body.selectors != null) {
+    return body.selectors;
+  }
+  return { items: { selector: 'a[href]', enhance: false } };
+}
+
+export function validateYamlForSelectors(selectors: unknown): string {
+  if (
+    typeof selectors === 'object' &&
+    selectors &&
+    'items' in selectors &&
+    typeof selectors.items === 'object' &&
+    selectors.items &&
+    'selector' in selectors.items &&
+    typeof selectors.items.selector === 'string'
+  ) {
+    const enhance =
+      'enhance' in selectors.items && selectors.items.enhance === true
+        ? '\n    enhance: true'
+        : '';
+    return `selectors:\n  items:\n    selector: ${selectors.items.selector}${enhance}\n`;
+  }
+  return 'selectors: {}\n';
+}
+
+export function validateSuccessBody(selectors?: unknown, yaml?: string) {
+  const resolved = selectors ?? { items: { selector: 'article' } };
   return {
     success: true,
     data: {
       report: { success: true, issues: [] },
-      selectors: selectors ?? { items: { selector: 'article' } },
-      yaml,
+      selectors: resolved,
+      yaml: yaml ?? validateYamlForSelectors(resolved),
     },
   };
 }
diff --git a/frontend/src/__tests__/mocks/server.ts b/frontend/src/__tests__/mocks/server.ts
index 63ca358b..9b00694e 100644
--- a/frontend/src/__tests__/mocks/server.ts
+++ b/frontend/src/__tests__/mocks/server.ts
@@ -3,9 +3,11 @@ import { http, HttpResponse } from 'msw';
 import {
   emptyCatalog,
   metadataBody,
+  selectorsFromValidateRequest,
   studioPreviewSuccessBody,
   suggestSuccessBody,
   validateSuccessBody,
+  validateYamlForSelectors,
   type CreatedFeedOverrides,
 } from './apiFixtures';
 
@@ -16,13 +18,9 @@ export const server = setupServer(
   http.get('/api/v1/configs', () => {
     return HttpResponse.json(emptyCatalog);
   }),
-  http.post('/api/v1/feeds/validate', () => {
-    return HttpResponse.json(
-      validateSuccessBody(
-        { items: { selector: 'article', enhance: false } },
-        'selectors:\n  items:\n    selector: article\n    enhance: false\n'
-      )
-    );
+  http.post('/api/v1/feeds/validate', async ({ request }) => {
+    const selectors = selectorsFromValidateRequest(await request.json());
+    return HttpResponse.json(validateSuccessBody(selectors, validateYamlForSelectors(selectors)));
   }),
   http.post('/api/v1/feeds/preview', () => {
     return HttpResponse.json(studioPreviewSuccessBody([]));

From 693fe94c7600ecb13d40cfa5ffe2ccfc0fb3c539 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Mon, 21 Sep 2026 10:25:20 +0200
Subject: [PATCH 064/108] feat(studio): return ranked selector candidates

Pin html2rss to the capture candidates commit and replace the single selectors suggestion with ranked items/title/link/published buckets on suggest_selectors.
---
 Gemfile                                      |  9 ++-
 Gemfile.lock                                 |  4 +-
 app/web/api/v1/suggest_selectors.rb          | 76 +++++++++++++++----
 frontend/src/__tests__/ConfigStudio.test.tsx |  4 +-
 frontend/src/__tests__/mocks/apiFixtures.ts  |  6 +-
 frontend/src/api/generated/index.ts          |  2 +-
 frontend/src/api/generated/types.gen.ts      | 32 +++++++-
 public/openapi.yaml                          | 60 ++++++++++++---
 spec/html2rss/web/api/v1_spec.rb             | 58 ++++++++++++--
 spec/support/openapi_studio_schemas.rb       | 79 +++++++++++++++++++-
 10 files changed, 280 insertions(+), 50 deletions(-)

diff --git a/Gemfile b/Gemfile
index 892744c3..c282adf0 100644
--- a/Gemfile
+++ b/Gemfile
@@ -4,10 +4,11 @@ source 'https://rubygems.org'
 
 git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
 
-# Pinned by revision, not by branch: the studio needs the gsub pattern bounds and
-# Config::IssueMapper, which no released 0.30.x gem carries. Bump this ref
-# deliberately; do not swap it for `branch:` or for a rubygems version constraint.
-gem 'html2rss', github: 'html2rss/html2rss', ref: 'fc5de54409c1d5e4a36836365d2e7909a084626e'
+# Pinned by revision, not by branch: the studio needs the gsub pattern bounds,
+# Config::IssueMapper, and CaptureResult#candidates, which no released 0.30.x
+# gem carries. Bump this ref deliberately; do not swap it for `branch:` or for
+# a rubygems version constraint.
+gem 'html2rss', github: 'html2rss/html2rss', ref: '8890cd37090b2f56c00ce8973a6c892517c14986'
 gem 'html2rss-configs', github: 'html2rss/html2rss-configs'
 
 # Use these instead of the two above (uncomment them) when developing locally:
diff --git a/Gemfile.lock b/Gemfile.lock
index 11c7bb1f..becfc1bd 100644
--- a/Gemfile.lock
+++ b/Gemfile.lock
@@ -1,7 +1,7 @@
 GIT
   remote: https://github.com/html2rss/html2rss
-  revision: fc5de54409c1d5e4a36836365d2e7909a084626e
-  ref: fc5de54409c1d5e4a36836365d2e7909a084626e
+  revision: 8890cd37090b2f56c00ce8973a6c892517c14986
+  ref: 8890cd37090b2f56c00ce8973a6c892517c14986
   specs:
     html2rss (0.30.0)
       addressable (~> 2.7)
diff --git a/app/web/api/v1/suggest_selectors.rb b/app/web/api/v1/suggest_selectors.rb
index 9121896e..afbc0489 100644
--- a/app/web/api/v1/suggest_selectors.rb
+++ b/app/web/api/v1/suggest_selectors.rb
@@ -5,10 +5,10 @@ module Web
     module Api
       module V1
         ##
-        # One capture-derived items selector for the refinement studio.
+        # Ranked capture-derived selector candidates for the refinement studio.
         #
-        # +Html2rss.capture+ returns the first segment strategy that clears its
-        # quality gate, not a candidate list.
+        # +Html2rss.capture+ publishes buckets on +CaptureResult#candidates+.
+        # Empty buckets are a successful response.
         module SuggestSelectors
           # Upper bound for the client-supplied items selector hint.
           MAX_ITEMS_SELECTOR_LENGTH = 256
@@ -55,23 +55,71 @@ def hint(raw)
             # @param captured [Html2rss::Capture::CaptureResult]
             # @return [Hash{Symbol=>Object}]
             def suggestion(captured)
-              selectors = captured.config[:selectors] || captured.config['selectors']
-              items = selectors.is_a?(Hash) ? selectors[:items] || selectors['items'] : nil
               {
-                selectors:,
+                candidates: candidate_buckets(captured.candidates),
                 segment_strategy: captured.segment_strategy&.to_s,
-                admission_drops: captured.admission_drops,
-                enhance: enhance_flag(items)
+                admission_drops: captured.admission_drops
               }
             end
 
-            # @param items [Hash, nil]
-            # @return [Boolean, nil]
-            def enhance_flag(items)
-              return unless items.is_a?(Hash)
-              return items[:enhance] if items.key?(:enhance)
+            # @param raw [Hash, nil]
+            # @return [Hash{Symbol=>Array<Hash>}]
+            def candidate_buckets(raw)
+              buckets = raw.is_a?(Hash) ? raw : {}
+              {
+                items: item_entries(bucket(buckets, :items)),
+                title: field_entries(bucket(buckets, :title)),
+                link: field_entries(bucket(buckets, :link)),
+                published: field_entries(bucket(buckets, :published))
+              }
+            end
+
+            # @param buckets [Hash]
+            # @param name [Symbol]
+            # @return [Array]
+            def bucket(buckets, name)
+              value = buckets.fetch(name) { buckets[name.to_s] }
+              value.is_a?(Array) ? value : []
+            end
+
+            # @param entries [Array]
+            # @return [Array<Hash>]
+            def item_entries(entries)
+              entries.filter_map { item_entry(it) }
+            end
+
+            # @param entry [Object]
+            # @return [Hash, nil]
+            def item_entry(entry)
+              selector = selector_text(entry)
+              return unless selector
+
+              { selector:, enhance: enhanced?(entry) }
+            end
+
+            # @param entries [Array]
+            # @return [Array<Hash>]
+            def field_entries(entries)
+              entries.filter_map do |entry|
+                selector = selector_text(entry)
+                { selector: } if selector
+              end
+            end
+
+            # @param entry [Object]
+            # @return [String, nil]
+            def selector_text(entry)
+              return unless entry.is_a?(Hash)
+
+              text = (entry[:selector] || entry['selector']).to_s.strip
+              text.empty? ? nil : text
+            end
 
-              items['enhance'] if items.key?('enhance')
+            # @param entry [Hash]
+            # @return [Boolean]
+            def enhanced?(entry)
+              flag = entry.key?(:enhance) ? entry[:enhance] : entry['enhance']
+              flag == true
             end
           end
         end
diff --git a/frontend/src/__tests__/ConfigStudio.test.tsx b/frontend/src/__tests__/ConfigStudio.test.tsx
index 0606b3c0..619ab501 100644
--- a/frontend/src/__tests__/ConfigStudio.test.tsx
+++ b/frontend/src/__tests__/ConfigStudio.test.tsx
@@ -143,9 +143,7 @@ describe('ConfigStudio', () => {
     await waitFor(() => expect(items).toHaveFocus());
     await waitFor(() => expect(items).toHaveValue('a[href]'));
     expect(screen.getByLabelText(COPY.enhanceItems)).toBeInTheDocument();
-    await waitFor(() =>
-      expect(screen.getByRole('button', { name: COPY.useSuggestion })).toBeInTheDocument()
-    );
+    await waitFor(() => expect(screen.getByRole('button', { name: COPY.useSuggestion })).toBeInTheDocument());
     expect(screen.getByRole('button', { name: COPY.fieldMissing(COPY.fieldTitle) })).toBeInTheDocument();
     expect(screen.getByRole('button', { name: COPY.fieldMissing(COPY.fieldLink) })).toBeInTheDocument();
     expect(screen.getByRole('button', { name: COPY.fieldMissing(COPY.fieldPublished) })).toBeInTheDocument();
diff --git a/frontend/src/__tests__/mocks/apiFixtures.ts b/frontend/src/__tests__/mocks/apiFixtures.ts
index 796f0c97..a557a94b 100644
--- a/frontend/src/__tests__/mocks/apiFixtures.ts
+++ b/frontend/src/__tests__/mocks/apiFixtures.ts
@@ -103,7 +103,7 @@ export function buildStructuredErrorResponse(overrides: StructuredErrorOverrides
 
 /** Prefer request selectors so validate does not invent an `article` items selector. */
 export function selectorsFromValidateRequest(body: unknown): unknown {
-  if (typeof body === 'object' && body && 'selectors' in body && body.selectors != null) {
+  if (typeof body === 'object' && body && 'selectors' in body && body.selectors !== undefined) {
     return body.selectors;
   }
   return { items: { selector: 'a[href]', enhance: false } };
@@ -120,9 +120,7 @@ export function validateYamlForSelectors(selectors: unknown): string {
     typeof selectors.items.selector === 'string'
   ) {
     const enhance =
-      'enhance' in selectors.items && selectors.items.enhance === true
-        ? '\n    enhance: true'
-        : '';
+      'enhance' in selectors.items && selectors.items.enhance === true ? '\n    enhance: true' : '';
     return `selectors:\n  items:\n    selector: ${selectors.items.selector}${enhance}\n`;
   }
   return 'selectors: {}\n';
diff --git a/frontend/src/api/generated/index.ts b/frontend/src/api/generated/index.ts
index fcaa243a..351544af 100644
--- a/frontend/src/api/generated/index.ts
+++ b/frontend/src/api/generated/index.ts
@@ -1,4 +1,4 @@
 // This file is auto-generated by @hey-api/openapi-ts
 
 export { createFeed, getApiMetadata, getConfigCatalog, getHealthStatus, getLivenessProbe, getReadinessProbe, listStrategies, type Options, optionsConfigCatalog, previewFeed, renderFeedByToken, suggestSelectors, validateFeedConfig } from './sdk.gen';
-export type { ClientOptions, CreateFeedData, CreateFeedError, CreateFeedErrors, CreateFeedResponse, CreateFeedResponses, GetApiMetadataData, GetApiMetadataResponse, GetApiMetadataResponses, GetConfigCatalogData, GetConfigCatalogError, GetConfigCatalogErrors, GetConfigCatalogResponse, GetConfigCatalogResponses, GetHealthStatusData, GetHealthStatusError, GetHealthStatusErrors, GetHealthStatusResponse, GetHealthStatusResponses, GetLivenessProbeData, GetLivenessProbeResponse, GetLivenessProbeResponses, GetReadinessProbeData, GetReadinessProbeResponse, GetReadinessProbeResponses, ListStrategiesData, ListStrategiesResponse, ListStrategiesResponses, OptionsConfigCatalogData, OptionsConfigCatalogResponse, OptionsConfigCatalogResponses, PreviewFeedData, PreviewFeedResponse, PreviewFeedResponses, PreviewSampleItem, RefinedSelectorKey, RefinedSelectorsDocument, RenderFeedByTokenData, RenderFeedByTokenError, RenderFeedByTokenErrors, RenderFeedByTokenResponse, RenderFeedByTokenResponses, SuggestSelectorsData, SuggestSelectorsResponse, SuggestSelectorsResponses, ValidateFeedConfigData, ValidateFeedConfigError, ValidateFeedConfigErrors, ValidateFeedConfigResponse, ValidateFeedConfigResponses } from './types.gen';
+export type { ClientOptions, CreateFeedData, CreateFeedError, CreateFeedErrors, CreateFeedResponse, CreateFeedResponses, FieldSelectorCandidate, GetApiMetadataData, GetApiMetadataResponse, GetApiMetadataResponses, GetConfigCatalogData, GetConfigCatalogError, GetConfigCatalogErrors, GetConfigCatalogResponse, GetConfigCatalogResponses, GetHealthStatusData, GetHealthStatusError, GetHealthStatusErrors, GetHealthStatusResponse, GetHealthStatusResponses, GetLivenessProbeData, GetLivenessProbeResponse, GetLivenessProbeResponses, GetReadinessProbeData, GetReadinessProbeResponse, GetReadinessProbeResponses, ItemsSelectorCandidate, ListStrategiesData, ListStrategiesResponse, ListStrategiesResponses, OptionsConfigCatalogData, OptionsConfigCatalogResponse, OptionsConfigCatalogResponses, PreviewFeedData, PreviewFeedResponse, PreviewFeedResponses, PreviewSampleItem, RefinedSelectorKey, RefinedSelectorsDocument, RenderFeedByTokenData, RenderFeedByTokenError, RenderFeedByTokenErrors, RenderFeedByTokenResponse, RenderFeedByTokenResponses, SelectorCandidates, SuggestSelectorsData, SuggestSelectorsResponse, SuggestSelectorsResponses, ValidateFeedConfigData, ValidateFeedConfigError, ValidateFeedConfigErrors, ValidateFeedConfigResponse, ValidateFeedConfigResponses } from './types.gen';
diff --git a/frontend/src/api/generated/types.gen.ts b/frontend/src/api/generated/types.gen.ts
index b623052a..2465bd10 100644
--- a/frontend/src/api/generated/types.gen.ts
+++ b/frontend/src/api/generated/types.gen.ts
@@ -41,6 +41,31 @@ export type PreviewSampleItem = {
   image?: string | null;
 };
 
+/**
+ * Ranked selector candidates. Empty buckets are a successful response.
+ */
+export type SelectorCandidates = {
+  items: Array<ItemsSelectorCandidate>;
+  title: Array<FieldSelectorCandidate>;
+  link: Array<FieldSelectorCandidate>;
+  published: Array<FieldSelectorCandidate>;
+};
+
+/**
+ * One ranked items selector. Best match is first in the bucket.
+ */
+export type ItemsSelectorCandidate = {
+  selector: string;
+  enhance: boolean;
+};
+
+/**
+ * One ranked field selector. Best match is first in the bucket.
+ */
+export type FieldSelectorCandidate = {
+  selector: string;
+};
+
 export type GetApiMetadataData = {
   body?: never;
   path?: never;
@@ -339,16 +364,15 @@ export type SuggestSelectorsData = {
 
 export type SuggestSelectorsResponses = {
   /**
-   * returns the capture suggestion and its evidence
+   * returns ranked selector candidates
    */
   200: {
     data: {
       admission_drops: {
-        chrome: number;
+        chrome?: number;
       };
-      enhance: boolean;
+      candidates: SelectorCandidates;
       segment_strategy: string;
-      selectors: RefinedSelectorsDocument;
     };
     success: boolean;
   };
diff --git a/public/openapi.yaml b/public/openapi.yaml
index 7f2e065f..8cf6cc8b 100644
--- a/public/openapi.yaml
+++ b/public/openapi.yaml
@@ -654,20 +654,15 @@ paths:
                         properties:
                           chrome:
                             type: integer
-                        required:
-                        - chrome
                         type: object
-                      enhance:
-                        type: boolean
+                      candidates:
+                        "$ref": "#/components/schemas/SelectorCandidates"
                       segment_strategy:
                         type: string
-                      selectors:
-                        "$ref": "#/components/schemas/RefinedSelectorsDocument"
                     required:
-                    - selectors
+                    - candidates
                     - segment_strategy
                     - admission_drops
-                    - enhance
                     type: object
                   success:
                     type: boolean
@@ -675,7 +670,7 @@ paths:
                 - success
                 - data
                 type: object
-          description: returns the capture suggestion and its evidence
+          description: returns ranked selector candidates
       security:
       - BearerAuth: []
       summary: Suggest selectors for a page
@@ -1275,6 +1270,53 @@ components:
         image:
           type: string
           nullable: true
+    SelectorCandidates:
+      description: Ranked selector candidates. Empty buckets are a successful response.
+      type: object
+      required:
+      - items
+      - title
+      - link
+      - published
+      additionalProperties: false
+      properties:
+        items:
+          type: array
+          items:
+            "$ref": "#/components/schemas/ItemsSelectorCandidate"
+        title:
+          type: array
+          items:
+            "$ref": "#/components/schemas/FieldSelectorCandidate"
+        link:
+          type: array
+          items:
+            "$ref": "#/components/schemas/FieldSelectorCandidate"
+        published:
+          type: array
+          items:
+            "$ref": "#/components/schemas/FieldSelectorCandidate"
+    ItemsSelectorCandidate:
+      description: One ranked items selector. Best match is first in the bucket.
+      type: object
+      required:
+      - selector
+      - enhance
+      additionalProperties: false
+      properties:
+        selector:
+          type: string
+        enhance:
+          type: boolean
+    FieldSelectorCandidate:
+      description: One ranked field selector. Best match is first in the bucket.
+      type: object
+      required:
+      - selector
+      additionalProperties: false
+      properties:
+        selector:
+          type: string
 tags:
 - name: Root
   description: API metadata and service-level information.
diff --git a/spec/html2rss/web/api/v1_spec.rb b/spec/html2rss/web/api/v1_spec.rb
index 493a4a03..f93fc995 100644
--- a/spec/html2rss/web/api/v1_spec.rb
+++ b/spec/html2rss/web/api/v1_spec.rb
@@ -1089,24 +1089,68 @@ def expected_capped_rows
     tags: ['Studio'],
     security: [{ 'BearerAuth' => [] }]
   } do
-    let(:captured) do
+    def ranked_candidates
+      {
+        items: [{ selector: 'article', enhance: false }, { selector: '.story', enhance: true }],
+        title: [{ selector: 'h2' }],
+        link: [{ selector: 'a' }],
+        published: [{ selector: 'time' }]
+      }
+    end
+
+    def wire_candidates
+      {
+        'items' => [
+          { 'selector' => 'article', 'enhance' => false },
+          { 'selector' => '.story', 'enhance' => true }
+        ],
+        'title' => [{ 'selector' => 'h2' }],
+        'link' => [{ 'selector' => 'a' }],
+        'published' => [{ 'selector' => 'time' }]
+      }
+    end
+
+    def empty_candidates = { items: [], title: [], link: [], published: [] }
+
+    def empty_wire_candidates
+      { 'items' => [], 'title' => [], 'link' => [], 'published' => [] }
+    end
+
+    def capture_double(candidates, admission_drops: { 'chrome' => 2 })
       instance_double(
         Html2rss::Capture::CaptureResult,
-        config: { selectors: { items: { selector: 'article', enhance: false } } },
         segment_strategy: :list,
-        admission_drops: { 'chrome' => 2 }
+        admission_drops:,
+        candidates:
       )
     end
 
-    it 'returns the capture suggestion and its evidence', :aggregate_failures do
-      allow(Html2rss).to receive(:capture).and_return(captured)
+    def post_suggest
       header 'Authorization', "Bearer #{admin_token}"
       header 'Content-Type', 'application/json'
       post '/api/v1/feeds/suggest_selectors', { url: feed_url, items_selector: 'h2' }.to_json
+    end
+
+    it 'returns empty candidate buckets as success', :aggregate_failures do
+      allow(Html2rss).to receive(:capture).and_return(capture_double(empty_candidates, admission_drops: {}))
+      post_suggest
+
+      json = expect_success_response(last_response)
+      expect(last_response.status).to eq(200)
+      expect(json.dig('data', 'candidates')).to eq(empty_wire_candidates)
+    end
+
+    it 'returns ranked selector candidates', :aggregate_failures do
+      allow(Html2rss).to receive(:capture).and_return(capture_double(ranked_candidates))
+      post_suggest
 
       json = expect_success_response(last_response)
-      expect(json.dig('data', 'segment_strategy')).to eq('list')
-      expect(json.dig('data', 'enhance')).to be(false)
+      expect(last_response.status).to eq(200)
+      expect(json.fetch('data')).to eq(
+        'candidates' => wire_candidates,
+        'segment_strategy' => 'list',
+        'admission_drops' => { 'chrome' => 2 }
+      )
     end
   end
 
diff --git a/spec/support/openapi_studio_schemas.rb b/spec/support/openapi_studio_schemas.rb
index ecb2d69a..8ffc017e 100644
--- a/spec/support/openapi_studio_schemas.rb
+++ b/spec/support/openapi_studio_schemas.rb
@@ -1,10 +1,13 @@
 # frozen_string_literal: true
 
 ##
-# Closed studio selector / preview schemas stamped into the OpenAPI document.
-module OpenapiStudioSchemas
+# Closed studio selector, preview, and candidate schemas stamped into the OpenAPI document.
+module OpenapiStudioSchemas # rubocop:disable Metrics/ModuleLength -- stamped studio schemas share one module
   REFINED_SELECTORS_REF = { '$ref' => '#/components/schemas/RefinedSelectorsDocument' }.freeze
   PREVIEW_SAMPLE_ITEM_REF = { '$ref' => '#/components/schemas/PreviewSampleItem' }.freeze
+  SELECTOR_CANDIDATES_REF = { '$ref' => '#/components/schemas/SelectorCandidates' }.freeze
+  ITEMS_CANDIDATE_REF = { '$ref' => '#/components/schemas/ItemsSelectorCandidate' }.freeze
+  FIELD_CANDIDATE_REF = { '$ref' => '#/components/schemas/FieldSelectorCandidate' }.freeze
 
   module_function
 
@@ -81,6 +84,9 @@ def preview_sample_properties
   def publish(schemas)
     schemas['RefinedSelectorsDocument'] = refined_selectors_document
     schemas['PreviewSampleItem'] = preview_sample_item
+    schemas['SelectorCandidates'] = selector_candidates
+    schemas['ItemsSelectorCandidate'] = items_selector_candidate
+    schemas['FieldSelectorCandidate'] = field_selector_candidate
   end
 
   # @param spec [Hash]
@@ -92,6 +98,7 @@ def rewrite(spec)
 
       rewrite_selectors_property(properties)
       rewrite_sample_items_property(properties)
+      rewrite_candidates_property(properties)
     end
   end
 
@@ -131,6 +138,74 @@ def selectors_document_hull?(schema)
     items.is_a?(Hash) && items.dig('properties', 'selector').is_a?(Hash)
   end
 
+  # @return [Hash]
+  def selector_candidates
+    {
+      'description' => 'Ranked selector candidates. Empty buckets are a successful response.',
+      'type' => 'object',
+      'required' => %w[items title link published],
+      'additionalProperties' => false,
+      'properties' => candidate_bucket_properties
+    }
+  end
+
+  # @return [Hash]
+  def candidate_bucket_properties
+    {
+      'items' => { 'type' => 'array', 'items' => ITEMS_CANDIDATE_REF.dup },
+      'title' => { 'type' => 'array', 'items' => FIELD_CANDIDATE_REF.dup },
+      'link' => { 'type' => 'array', 'items' => FIELD_CANDIDATE_REF.dup },
+      'published' => { 'type' => 'array', 'items' => FIELD_CANDIDATE_REF.dup }
+    }
+  end
+
+  # @return [Hash]
+  def items_selector_candidate
+    {
+      'description' => 'One ranked items selector. Best match is first in the bucket.',
+      'type' => 'object',
+      'required' => %w[selector enhance],
+      'additionalProperties' => false,
+      'properties' => {
+        'selector' => { 'type' => 'string' },
+        'enhance' => { 'type' => 'boolean' }
+      }
+    }
+  end
+
+  # @return [Hash]
+  def field_selector_candidate
+    {
+      'description' => 'One ranked field selector. Best match is first in the bucket.',
+      'type' => 'object',
+      'required' => %w[selector],
+      'additionalProperties' => false,
+      'properties' => {
+        'selector' => { 'type' => 'string' }
+      }
+    }
+  end
+
+  # @param properties [Hash]
+  # @return [void]
+  def rewrite_candidates_property(properties)
+    schema = properties['candidates']
+    return unless candidates_hull?(schema)
+
+    properties['candidates'] = SELECTOR_CANDIDATES_REF.dup
+  end
+
+  # @param schema [Object]
+  # @return [Boolean]
+  def candidates_hull?(schema)
+    return false unless schema.is_a?(Hash)
+
+    properties = schema['properties']
+    return false unless properties.is_a?(Hash)
+
+    %w[items title link published].all? { properties[it].is_a?(Hash) }
+  end
+
   # @param schema [Object]
   # @return [Boolean]
   def sample_items_hull?(schema)

From 836c2fcbb6f9ac50e23490925e5889f4d39f9c15 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Mon, 21 Sep 2026 10:44:34 +0200
Subject: [PATCH 065/108] feat(refine): offer ranked selector choices

Map suggest candidates through studioService and render explicit per-bucket Use actions in gated refine without auto-applying into the draft.
---
 CONTEXT.md                                   |   2 +-
 docs/design-system.md                        |   4 +-
 frontend/e2e/smoke.spec.ts                   |  36 +++--
 frontend/src/__tests__/ConfigStudio.test.tsx | 134 ++++++++++++++----
 frontend/src/__tests__/mocks/apiFixtures.ts  |  37 ++++-
 frontend/src/__tests__/useStudio.test.ts     | 136 +++++++++++++++++--
 frontend/src/components/ConfigStudio.tsx     | 125 ++++++++++++++---
 frontend/src/journey/copy.ts                 |   4 +-
 frontend/src/studio/selectorDraft.ts         |  32 ++++-
 frontend/src/studio/studioService.ts         |  75 ++++++++--
 frontend/src/studio/useStudio.ts             |  20 ++-
 frontend/src/styles/main.css                 |  25 ++++
 12 files changed, 536 insertions(+), 94 deletions(-)

diff --git a/CONTEXT.md b/CONTEXT.md
index 82f68279..707e76a9 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -29,7 +29,7 @@ On create, `findCatalogEntries` matches the typed query against the catalog (URL
 Visiting create (including hashbang `#!/…` → `#/…`) bumps `createEntryKey` so the create surface remounts. Remount alone does not auto-submit; auto-submit requires `prefillUrl`.
 
 ### Config Studio
-Selector refinement for a token holder when studio is enabled. On a successful result, refinement is available on demand behind demoted **Refine selectors** on `#/result/:token` (collapsed by default; one meadow; live studio output replaces the result preview when expanded). `#/refine` is only extraction-empty recovery when no result exists. Memory-bound to the in-memory page URL (no token in the route). The visual builder and YAML are one document; only `studioService` unwraps the studio envelope. A server suggestion is held separately from the authored draft until the user accepts it. Save posts refined selectors through Creation IO and stays on the result view.
+Selector refinement for a token holder when studio is enabled. On a successful result, refinement is available on demand behind demoted **Refine selectors** on `#/result/:token` (collapsed by default; one meadow; live studio output replaces the result preview when expanded). `#/refine` is only extraction-empty recovery when no result exists. Memory-bound to the in-memory page URL (no token in the route). The visual builder and YAML are one document; only `studioService` unwraps the studio envelope and maps ranked `candidates` (items / title / link / published) into domain suggestion buckets. Candidates never auto-apply — each **Use** applies only that clicked choice; rows already matching the draft stay hidden. Field extractors remain fixed by the draft mapper. Save posts refined selectors through Creation IO and stays on the result view.
 
 ### Refined Selectors
 The allowlisted `selectors` document a token holder may attach on feed creation. Signed into the feed token and resolved on later serves. Not a full config: channel, headers, and strategy stay denied.
diff --git a/docs/design-system.md b/docs/design-system.md
index 15013fbe..40d1a1e8 100644
--- a/docs/design-system.md
+++ b/docs/design-system.md
@@ -42,7 +42,7 @@ If a page looks like it came from a different product, the change is wrong even
 - **Token gate:** a native `<dialog>` over the still-mounted, inert URL task (one interactive task). Auth copy is in-field (`tokenError`); ActionFeedback stays on create. Access Token persists until Logout with no storage UI.
 - **Result:** primary CTA is **Copy feed URL**, and it takes initial focus. Open feed / JSON / feed-reader are demoted secondary actions and stay available while preview loads. Preview is one meadow and non-blocking confirmation only. Guest results stay compact: at most 5 items, no images, no selector controls. An authenticated, studio-enabled result keeps that same frame: a demoted **Refine selectors** action in `ui-actions` (collapsed by default). Opening it mounts selector controls **above** the meadow; closing it returns to the static meadow without discarding the in-memory draft. Studio validate/preview/suggest do not run until the panel opens. Selector edits replace the meadow with live studio output; they do not add a second list. **Save and generate feed** is the only primary action inside those controls. Member previews may show up to 10 items and safe HTTP(S) images.
 - **Empty extraction:** **Refine selectors** is one quiet action beside Try again when the extraction is empty, studio is enabled, and an access token is present. It is not offered for other create errors, guests, or a studio-off instance.
-- **Refine:** `#/refine` is memory-bound extraction-empty recovery for an authenticated studio (see [personas.md](personas.md) J2). No token in the route. A successful in-memory result replaces `#/refine` with `#/result/:token`; refinement of that feed stays on the result behind the same demoted **Refine selectors** gate. Standalone recovery uses the same frame as an expanded Result: a `result-shell` / `layout-stack` rail — never a mega-card bisected by the fixed footer, never a two-column paddock. First viewport leads with compact controls (items selector, visible **Suggested:** chip + **Use**, a large Enhance hit target, and **Save and generate feed** as the only `btn--primary` in `ui-actions`), then the live preview meadow (`.ui-item-list`) after validation. URL, native-feed Notice, and View as YAML are demoted support below the meadow. Changing the URL re-suggests and re-previews without leaving the current surface or running catalog find; empty URL recovers onto remounted `#/create`. Suggestion is held separately from the authored draft and shown as a comparable chip; **Use** applies items + Enhance only when the user accepts. Wire is the typed closed selectors document (no strip/trim/affix cleanup UI). Fix a field opens one selector panel **in the stack** for Title, Link, or Published date. View as YAML is read-only and captioned as a selectors fragment — not a feeds.yml. Save-failure Notices use wire `Decision#message` — never create-journey copy. When studio is disabled or the caller has no token, Refine actions stay hidden and `#/refine` bounces to create. Focus on standalone recovery is the items selector; a successful Result keeps focus on Copy whether Refine is open or closed.
+- **Refine:** `#/refine` is memory-bound extraction-empty recovery for an authenticated studio (see [personas.md](personas.md) J2). No token in the route. A successful in-memory result replaces `#/refine` with `#/result/:token`; refinement of that feed stays on the result behind the same demoted **Refine selectors** gate. Standalone recovery uses the same frame as an expanded Result: a `result-shell` / `layout-stack` rail — never a mega-card bisected by the fixed footer, never a two-column paddock. First viewport leads with compact controls (items selector, ranked **Selector choices** per bucket with explicit **Use** actions, a large Enhance hit target, and **Save and generate feed** as the only `btn--primary` in `ui-actions`), then the live preview meadow (`.ui-item-list`) after validation. URL, native-feed Notice, and View as YAML are demoted support below the meadow. Changing the URL re-suggests and re-previews without leaving the current surface or running catalog find; empty URL recovers onto remounted `#/create`. Ranked candidates (items, title, link, published) stay separate from the authored draft until the user clicks **Use** on one row; that click applies only that candidate, and rows already matching the draft are hidden. Empty buckets stay hidden. Wire is the typed closed selectors document (no strip/trim/affix cleanup UI). Fix a field opens one selector panel **in the stack** for Title, Link, or Published date. View as YAML is read-only and captioned as a selectors fragment — not a feeds.yml. Save-failure Notices use wire `Decision#message` — never create-journey copy. When studio is disabled or the caller has no token, Refine actions stay hidden and `#/refine` bounces to create. Focus on standalone recovery is the items selector; a successful Result keeps focus on Copy whether Refine is open or closed.
 - **Unmatched result:** `#/result/:token` is valid only with a matching in-memory result. Missing or mismatched tokens recover onto remounted `#/create` (no API rehydrate, no failure chrome, no durable shareable result page).
 - **Status eyebrow:** one vocabulary (`Feed ready`) on the result header; preview progress lives in the preview section.
 - **Focus:** create autofocuses the URL field; token autofocuses the token field; result focuses the Copy control; standalone extraction-empty refine focuses the items selector.
@@ -55,7 +55,7 @@ If a page looks like it came from a different product, the change is wrong even
 | Output | **Feed URL** |
 | Create | **Create feed** / **Creating feed** |
 | Result | **Feed ready** / **Copy feed URL** |
-| Refine | **Refine selectors** / **Suggested:** / **Use** / **Save and generate feed** / **View as YAML** |
+| Refine | **Refine selectors** / **Selector choices** / **Use** / **Save and generate feed** / **View as YAML** |
 | Retry | **Try again** (button only) |
 | Preview | **Checking preview** / **Check again** |
 | Catalog | **Feed Directory** |
diff --git a/frontend/e2e/smoke.spec.ts b/frontend/e2e/smoke.spec.ts
index 821ea60e..e90f83d5 100644
--- a/frontend/e2e/smoke.spec.ts
+++ b/frontend/e2e/smoke.spec.ts
@@ -5,9 +5,11 @@ import {
   emptyCatalog,
   jsonPreviewItems,
   metadataBody,
+  selectorsFromValidateRequest,
   studioPreviewSuccessBody,
   suggestSuccessBody,
   validateSuccessBody,
+  validateYamlForSelectors,
   type MetadataOptions,
 } from '../src/__tests__/mocks/apiFixtures';
 
@@ -50,7 +52,17 @@ function isSameOriginApi(url: string, path: RegExp): boolean {
 }
 
 async function stubStudioEndpoints(page: Page) {
-  await fulfillJson(page, API_VALIDATE, validateSuccessBody({ items: { selector: 'article' } }));
+  await page.route(API_VALIDATE, async (route) => {
+    const request = route.request();
+    const posted = request.postDataJSON() as unknown;
+    const selectors = selectorsFromValidateRequest(posted);
+    const body = validateSuccessBody(selectors, validateYamlForSelectors(selectors));
+    await route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify(body),
+    });
+  });
   await fulfillJson(page, API_SUGGEST, suggestSuccessBody('article', false));
   await fulfillJson(page, API_STUDIO_PREVIEW, studioPreviewSuccessBody());
 }
@@ -89,7 +101,7 @@ test.describe('frontend smoke', () => {
 
     await expect(page.getByLabel(COPY.urlLabel)).toBeVisible();
     await expect(page.getByRole('button', { name: COPY.createFeed })).toBeVisible();
-    expect(catalogUrls.length).toBeGreaterThan(0);
+    await expect.poll(() => catalogUrls.length, { timeout: 5000 }).toBeGreaterThan(0);
     expect(catalogUrls.every((url) => isSameOriginApi(url, API_CONFIGS))).toBe(true);
 
     await page.getByLabel(COPY.urlLabel).fill(EXAMPLE_URL);
@@ -186,7 +198,7 @@ test.describe('frontend smoke', () => {
     const refine = page.getByRole('button', { name: COPY.refineSelectors });
     await expect(refine).toBeVisible();
     await expect(refine).toHaveAttribute('aria-expanded', 'false');
-    await expect(page.getByLabel(COPY.itemsSelector)).toHaveCount(0);
+    await expect(page.getByLabel(COPY.itemsSelector, { exact: true })).toHaveCount(0);
     await expect(page.locator('.ui-item-list')).toHaveCount(1);
     await expect(page.getByText('Sample preview item')).toBeVisible();
     await expect(page.getByText('Current preview fetch includes rendered content.')).toBeVisible();
@@ -223,7 +235,7 @@ test.describe('frontend smoke', () => {
     const refine = page.getByRole('button', { name: COPY.refineSelectors });
     await expect(refine).toBeVisible();
     await expect(refine).toHaveAttribute('aria-expanded', 'false');
-    await expect(page.getByLabel(COPY.itemsSelector)).toHaveCount(0);
+    await expect(page.getByLabel(COPY.itemsSelector, { exact: true })).toHaveCount(0);
     await expect(page.locator('.ui-card')).toHaveCount(0);
     expect(validateRequests).toHaveLength(0);
     expect(previewRequests).toHaveLength(0);
@@ -231,10 +243,18 @@ test.describe('frontend smoke', () => {
     await refine.click();
     await expect(refine).toHaveAttribute('aria-expanded', 'true');
 
-    const items = page.getByLabel(COPY.itemsSelector);
+    const items = page.getByLabel(COPY.itemsSelector, { exact: true });
     await expect(items).toBeVisible();
     await expect.poll(() => validateRequests.length, { timeout: 5000 }).toBeGreaterThan(0);
-    await items.fill('article');
+    await expect(page.getByRole('group', { name: COPY.selectorChoices, exact: true })).toBeVisible();
+    const itemsChoices = page.getByRole('group', {
+      name: COPY.choicesFor(COPY.itemsSelector),
+      exact: true,
+    });
+    await expect(itemsChoices.getByRole('button', { name: COPY.useSuggestion })).toBeVisible();
+    await itemsChoices.getByRole('button', { name: COPY.useSuggestion }).click();
+    await expect(items).toHaveValue('article');
+    await expect(page.getByRole('group', { name: COPY.selectorChoices, exact: true })).toHaveCount(0);
     await expect(page.getByText('Refine meadow item')).toBeVisible();
     await expect(page.locator('.ui-item-list')).toHaveCount(1);
     const meadow = page.getByLabel(COPY.previewRegion, { exact: true });
@@ -275,7 +295,7 @@ test.describe('frontend smoke', () => {
     expect(previewRequests).toHaveLength(0);
 
     await page.getByRole('button', { name: COPY.refineSelectors }).click();
-    await expect(page.getByLabel(COPY.itemsSelector)).toBeVisible();
+    await expect(page.getByLabel(COPY.itemsSelector, { exact: true })).toBeVisible();
     await expect.poll(() => suggestRequests.length, { timeout: 5000 }).toBeGreaterThan(0);
 
     const suggestBeforeEdit = suggestRequests.length;
@@ -317,7 +337,7 @@ test.describe('frontend smoke', () => {
     await expect(page.locator('.result-shell')).toHaveAttribute('data-state', 'result');
     await expect(page.getByRole('heading', { name: COPY.refineSelectors })).toHaveCount(0);
     await expect(page.getByRole('button', { name: COPY.refineSelectors })).toBeVisible();
-    await expect(page.getByLabel(COPY.itemsSelector)).toHaveCount(0);
+    await expect(page.getByLabel(COPY.itemsSelector, { exact: true })).toHaveCount(0);
   });
 
   test('hides refine when studio is disabled and bounces forced refine onto create', async ({ page }) => {
diff --git a/frontend/src/__tests__/ConfigStudio.test.tsx b/frontend/src/__tests__/ConfigStudio.test.tsx
index 619ab501..f3625e16 100644
--- a/frontend/src/__tests__/ConfigStudio.test.tsx
+++ b/frontend/src/__tests__/ConfigStudio.test.tsx
@@ -1,10 +1,12 @@
 import { describe, it, expect, vi } from 'vitest';
-import { render, screen, fireEvent, waitFor, act } from '@testing-library/preact';
+import { render, screen, fireEvent, waitFor, act, within } from '@testing-library/preact';
 import { http, HttpResponse } from 'msw';
 import type { RefinedSelectorsDocument } from '../api/generated/types.gen';
 import { server } from './mocks/server';
 import {
+  rankedSuggestSuccessBody,
   selectorsFromValidateRequest,
+  suggestSuccessBody,
   validateSuccessBody,
   validateYamlForSelectors,
 } from './mocks/apiFixtures';
@@ -23,16 +25,7 @@ vi.mock('../studio/useStudio', async (importOriginal) => {
 const pageUrl = 'https://example.com/articles';
 
 function suggestEnvelope(selector = 'article', isEnhanced = false, extras: Record<string, unknown> = {}) {
-  return {
-    success: true,
-    data: {
-      selectors: { items: { selector, enhance: isEnhanced } },
-      segment_strategy: 'list',
-      admission_drops: { chrome: 0 },
-      enhance: isEnhanced,
-      ...extras,
-    },
-  };
+  return suggestSuccessBody(selector, isEnhanced, extras);
 }
 
 function validateEnvelope(selectors?: unknown, report?: { success: boolean; issues: unknown[] }) {
@@ -113,6 +106,20 @@ function renderStudio(
   return { onGenerate, onUrlChange, onUrlCleared };
 }
 
+function itemsChoiceUse() {
+  return within(screen.getByRole('group', { name: COPY.choicesFor(COPY.itemsSelector) })).getAllByRole(
+    'button',
+    {
+      name: COPY.useSuggestion,
+    }
+  )[0]!;
+}
+
+async function waitForItemsChoiceUse() {
+  await waitFor(() => expect(itemsChoiceUse()).toBeInTheDocument());
+  return itemsChoiceUse();
+}
+
 describe('ConfigStudio', () => {
   it('leads with the items selector above the preview meadow when live preview is ready', async () => {
     echoValidate();
@@ -143,7 +150,7 @@ describe('ConfigStudio', () => {
     await waitFor(() => expect(items).toHaveFocus());
     await waitFor(() => expect(items).toHaveValue('a[href]'));
     expect(screen.getByLabelText(COPY.enhanceItems)).toBeInTheDocument();
-    await waitFor(() => expect(screen.getByRole('button', { name: COPY.useSuggestion })).toBeInTheDocument());
+    await waitFor(() => expect(itemsChoiceUse()).toBeInTheDocument());
     expect(screen.getByRole('button', { name: COPY.fieldMissing(COPY.fieldTitle) })).toBeInTheDocument();
     expect(screen.getByRole('button', { name: COPY.fieldMissing(COPY.fieldLink) })).toBeInTheDocument();
     expect(screen.getByRole('button', { name: COPY.fieldMissing(COPY.fieldPublished) })).toBeInTheDocument();
@@ -186,7 +193,7 @@ describe('ConfigStudio', () => {
     expect(onUrlCleared).toHaveBeenCalledTimes(1);
   });
 
-  it('shows a[href] immediately and a visible suggestion chip once suggest returns', async () => {
+  it('shows a[href] immediately and ranked choices once suggest returns', async () => {
     echoValidate();
     const pendingSuggestion = Promise.withResolvers<Response>();
     server.use(http.post('/api/v1/feeds/suggest_selectors', () => pendingSuggestion.promise));
@@ -194,30 +201,48 @@ describe('ConfigStudio', () => {
 
     const items = screen.getByLabelText(COPY.itemsSelector);
     expect(items).toHaveValue('a[href]');
+    expect(screen.queryByRole('group', { name: COPY.selectorChoices })).not.toBeInTheDocument();
 
     pendingSuggestion.resolve(HttpResponse.json(suggestEnvelope('.post', true)));
 
     await waitFor(() => expect(screen.getByText('.post')).toBeInTheDocument());
-    expect(screen.getByText(COPY.suggestedSelectorLabel)).toBeInTheDocument();
+    expect(screen.getByRole('group', { name: COPY.selectorChoices })).toBeInTheDocument();
     expect(items).toHaveValue('a[href]');
     expect(screen.getByLabelText(COPY.enhanceItems)).not.toBeChecked();
   });
 
-  it('shows the suggestion chip without overwriting the draft', async () => {
+  it('shows ranked choices without overwriting the draft', async () => {
     echoValidate();
-    stubSuggest(suggestEnvelope('.post', true, { admission_drops: { chrome: 2 } }));
+    stubSuggest(
+      rankedSuggestSuccessBody(
+        {
+          items: [
+            { selector: '.post', enhance: true },
+            { selector: 'article', enhance: false },
+          ],
+          title: [{ selector: 'h2' }],
+          link: [{ selector: 'a' }],
+          published: [{ selector: 'time' }],
+        },
+        { admission_drops: { chrome: 2 } }
+      )
+    );
     renderStudio();
 
     await waitFor(() => expect(screen.getByText('.post')).toBeInTheDocument());
     expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('a[href]');
     expect(screen.getByLabelText(COPY.enhanceItems)).not.toBeChecked();
+    expect(screen.getByText('article')).toBeInTheDocument();
+    expect(screen.getByText('h2')).toBeInTheDocument();
+    expect(screen.getByText('a')).toBeInTheDocument();
+    expect(screen.getByText('time')).toBeInTheDocument();
     expect(screen.queryByText('list')).not.toBeInTheDocument();
     expect(screen.queryByText(/chrome/)).not.toBeInTheDocument();
-    expect(screen.getByRole('button', { name: COPY.useSuggestion })).toHaveClass('btn--quiet');
+    expect(itemsChoiceUse()).toHaveClass('btn--quiet');
     expect(screen.getByRole('button', { name: COPY.saveAndGenerate }).closest('.ui-actions')).not.toBeNull();
   });
 
-  it('does not overwrite a typed items selector with the suggestion', async () => {
+  it('does not overwrite a typed items selector with candidates', async () => {
     echoValidate();
     const pendingSuggestion = Promise.withResolvers<Response>();
     server.use(http.post('/api/v1/feeds/suggest_selectors', () => pendingSuggestion.promise));
@@ -230,22 +255,79 @@ describe('ConfigStudio', () => {
     expect(screen.getByLabelText(COPY.enhanceItems)).not.toBeChecked();
   });
 
-  it('applies the stored suggestion when Use is clicked', async () => {
+  it('applies only the clicked items candidate when Use is pressed', async () => {
     echoValidate();
-    stubSuggest(suggestEnvelope('.post', true, { admission_drops: { chrome: 2 } }));
+    stubSuggest(
+      rankedSuggestSuccessBody({
+        items: [
+          { selector: '.post', enhance: true },
+          { selector: 'article', enhance: false },
+        ],
+        title: [{ selector: 'h2' }],
+      })
+    );
     renderStudio();
-    await waitFor(() => expect(screen.getByRole('button', { name: COPY.useSuggestion })).toBeInTheDocument());
+    await waitFor(() => expect(itemsChoiceUse()).toBeInTheDocument());
 
     fireEvent.input(screen.getByLabelText(COPY.itemsSelector), { target: { value: 'article.bad' } });
     expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('article.bad');
     expect(screen.getByLabelText(COPY.enhanceItems)).not.toBeChecked();
 
-    fireEvent.click(screen.getByRole('button', { name: COPY.useSuggestion }));
+    const itemsGroup = screen.getByRole('group', { name: COPY.choicesFor(COPY.itemsSelector) });
+    const useButtons = within(itemsGroup).getAllByRole('button', { name: COPY.useSuggestion });
+    fireEvent.click(useButtons[0]!);
 
     expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('.post');
     expect(screen.getByLabelText(COPY.enhanceItems)).toBeChecked();
-    expect(screen.queryByRole('button', { name: COPY.useSuggestion })).not.toBeInTheDocument();
-    expect(screen.queryByText(/chrome/)).not.toBeInTheDocument();
+    expect(screen.getByText('article')).toBeInTheDocument();
+    expect(screen.queryByText('.post')).not.toBeInTheDocument();
+    expect(screen.getByText('h2')).toBeInTheDocument();
+    expect(screen.getByRole('group', { name: COPY.choicesFor(COPY.fieldTitle) })).toBeInTheDocument();
+  });
+
+  it('applies a field candidate without changing items', async () => {
+    echoValidate();
+    stubSuggest(
+      rankedSuggestSuccessBody({
+        items: [{ selector: 'article', enhance: false }],
+        title: [{ selector: 'h2' }, { selector: 'h1' }],
+      })
+    );
+    renderStudio();
+    await waitFor(() => expect(screen.getByText('h2')).toBeInTheDocument());
+
+    const titleGroup = screen.getByRole('group', { name: COPY.choicesFor(COPY.fieldTitle) });
+    fireEvent.click(within(titleGroup).getAllByRole('button', { name: COPY.useSuggestion })[0]!);
+
+    fireEvent.click(screen.getByRole('button', { name: COPY.fieldMissing(COPY.fieldTitle) }));
+    expect(screen.getByLabelText(COPY.selector)).toHaveValue('h2');
+    expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('a[href]');
+    const remainingTitle = screen.getByRole('group', { name: COPY.choicesFor(COPY.fieldTitle) });
+    expect(within(remainingTitle).queryByText('h2')).not.toBeInTheDocument();
+    expect(within(remainingTitle).getByText('h1')).toBeInTheDocument();
+  });
+
+  it('hides empty candidate buckets', async () => {
+    echoValidate();
+    stubSuggest(rankedSuggestSuccessBody({ items: [{ selector: 'article', enhance: false }] }));
+    renderStudio();
+
+    await waitFor(() => expect(screen.getByText('article')).toBeInTheDocument());
+    expect(screen.getByRole('group', { name: COPY.selectorChoices })).toBeInTheDocument();
+    expect(screen.queryByRole('group', { name: COPY.choicesFor(COPY.fieldTitle) })).not.toBeInTheDocument();
+    expect(screen.queryByRole('group', { name: COPY.choicesFor(COPY.fieldLink) })).not.toBeInTheDocument();
+    expect(
+      screen.queryByRole('group', { name: COPY.choicesFor(COPY.fieldPublished) })
+    ).not.toBeInTheDocument();
+  });
+
+  it('hides the choices region when every bucket is empty', async () => {
+    echoValidate();
+    stubSuggest(rankedSuggestSuccessBody({}));
+    renderStudio();
+
+    await waitFor(() => expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('a[href]'));
+    expect(screen.queryByRole('group', { name: COPY.selectorChoices })).not.toBeInTheDocument();
   });
 
   it('opens a fix-a-field selector panel without cleanup controls', async () => {
@@ -367,7 +449,7 @@ describe('ConfigStudio', () => {
   it('reveals read-only yaml captioned as a selectors fragment', async () => {
     renderStudio();
     await waitFor(() => expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('a[href]'));
-    fireEvent.click(await screen.findByRole('button', { name: COPY.useSuggestion }));
+    fireEvent.click(await waitForItemsChoiceUse());
     await waitFor(() => expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('article'));
 
     fireEvent.click(screen.getByRole('button', { name: COPY.viewAsYaml }));
@@ -382,7 +464,7 @@ describe('ConfigStudio', () => {
     const save = screen.getByRole('button', { name: COPY.saveAndGenerate });
     expect(save).toBeDisabled();
     await waitFor(() => expect(save).toBeEnabled());
-    fireEvent.click(await screen.findByRole('button', { name: COPY.useSuggestion }));
+    fireEvent.click(await waitForItemsChoiceUse());
     await waitFor(() => expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('article'));
     await waitFor(() => expect(save).toBeEnabled());
 
diff --git a/frontend/src/__tests__/mocks/apiFixtures.ts b/frontend/src/__tests__/mocks/apiFixtures.ts
index a557a94b..2d1c6651 100644
--- a/frontend/src/__tests__/mocks/apiFixtures.ts
+++ b/frontend/src/__tests__/mocks/apiFixtures.ts
@@ -143,13 +143,46 @@ export function suggestSuccessBody(
   isEnhanced = false,
   extras: Record<string, unknown> = {}
 ) {
+  const { candidates, ...rest } = extras;
   return {
     success: true,
     data: {
-      selectors: { items: { selector, enhance: isEnhanced } },
+      candidates: candidates ?? {
+        items: [{ selector, enhance: isEnhanced }],
+        title: [],
+        link: [],
+        published: [],
+      },
+      segment_strategy: 'list',
+      admission_drops: { chrome: 0 },
+      ...rest,
+    },
+  };
+}
+
+export function rankedSuggestSuccessBody(
+  buckets: {
+    items?: Array<{ selector: string; enhance?: boolean }>;
+    title?: Array<{ selector: string }>;
+    link?: Array<{ selector: string }>;
+    published?: Array<{ selector: string }>;
+  } = {},
+  extras: Record<string, unknown> = {}
+) {
+  return {
+    success: true,
+    data: {
+      candidates: {
+        items: (buckets.items ?? []).map((entry) => ({
+          selector: entry.selector,
+          enhance: entry.enhance === true,
+        })),
+        title: buckets.title ?? [],
+        link: buckets.link ?? [],
+        published: buckets.published ?? [],
+      },
       segment_strategy: 'list',
       admission_drops: { chrome: 0 },
-      enhance: isEnhanced,
       ...extras,
     },
   };
diff --git a/frontend/src/__tests__/useStudio.test.ts b/frontend/src/__tests__/useStudio.test.ts
index 7886be38..d9f9cca6 100644
--- a/frontend/src/__tests__/useStudio.test.ts
+++ b/frontend/src/__tests__/useStudio.test.ts
@@ -4,6 +4,8 @@ import {
   draftFromSelectors,
   emptyDraft,
   selectorsFromDraft,
+  unusedFieldCandidates,
+  unusedItemsCandidates,
   withFieldSelector,
 } from '../studio/selectorDraft';
 import { STUDIO_PREVIEW_SETTLE_MS, STUDIO_VALIDATE_DELAY_MS, useStudio } from '../studio/useStudio';
@@ -45,10 +47,38 @@ function suggestionBody(isEnhanced = false, selector = 'article') {
   return {
     success: true,
     data: {
-      selectors: { items: { selector, enhance: isEnhanced } },
+      candidates: {
+        items: [{ selector, enhance: isEnhanced }],
+        title: [],
+        link: [],
+        published: [],
+      },
       segment_strategy: 'list',
       admission_drops: { chrome: 2 },
-      enhance: isEnhanced,
+    },
+  };
+}
+
+function rankedSuggestionBody(buckets: {
+  items?: Array<{ selector: string; enhance?: boolean }>;
+  title?: Array<{ selector: string }>;
+  link?: Array<{ selector: string }>;
+  published?: Array<{ selector: string }>;
+}) {
+  return {
+    success: true,
+    data: {
+      candidates: {
+        items: (buckets.items ?? []).map((entry) => ({
+          selector: entry.selector,
+          enhance: entry.enhance === true,
+        })),
+        title: buckets.title ?? [],
+        link: buckets.link ?? [],
+        published: buckets.published ?? [],
+      },
+      segment_strategy: 'list',
+      admission_drops: { chrome: 0 },
     },
   };
 }
@@ -161,6 +191,25 @@ describe('selector draft', () => {
       })
     ).toBeUndefined();
   });
+
+  it('hides items and field candidates that already match the draft', () => {
+    const drafted = draftFromSelectors({
+      items: { selector: 'article', enhance: true },
+      title: { selector: 'h2', extractor: 'text' },
+    });
+    expect(drafted).toBeDefined();
+    if (!drafted) return;
+
+    expect(
+      unusedItemsCandidates(drafted, [
+        { selector: 'article', enhance: true },
+        { selector: '.post', enhance: false },
+      ])
+    ).toEqual([{ selector: '.post', enhance: false }]);
+    expect(unusedFieldCandidates(drafted, 'title', [{ selector: 'h2' }, { selector: 'h1' }])).toEqual([
+      { selector: 'h1' },
+    ]);
+  });
 });
 
 describe('useStudio', () => {
@@ -189,7 +238,7 @@ describe('useStudio', () => {
       await Promise.resolve();
     });
     expect(callsTo(fetchMock, '/feeds/validate')).toHaveLength(0);
-    expect(result.current.suggestion?.itemsSelector).toBe('article');
+    expect(result.current.suggestion.items[0]?.selector).toBe('article');
     expect(result.current.state.draft.itemsSelector).toBe('a[href]');
 
     await advanceValidate(STUDIO_VALIDATE_DELAY_MS - 1);
@@ -323,7 +372,7 @@ describe('useStudio', () => {
     await waitFor(() => {
       expect(callsTo(fetchMock, '/feeds/validate').length).toBeGreaterThan(0);
     });
-    await waitFor(() => expect(result.current.suggestion?.itemsSelector).toBe('article'));
+    await waitFor(() => expect(result.current.suggestion.items[0]?.selector).toBe('article'));
     expect(callsTo(fetchMock, '/feeds/preview')).toHaveLength(0);
     expect(result.current.state.live.status).toBe('idle');
     expect(result.current.state.draft.itemsSelector).toBe('a[href]');
@@ -338,7 +387,7 @@ describe('useStudio', () => {
     expect(result.current.state.live.status).toBe('ready');
   });
 
-  it('stores a suggestion without overwriting the draft until accepted', async () => {
+  it('stores ranked candidates without overwriting the draft until Use is applied', async () => {
     const pendingSuggestion = Promise.withResolvers<Response>();
     mockStudioFetch(fetchMock, {
       suggest: () => pendingSuggestion.promise,
@@ -356,6 +405,7 @@ describe('useStudio', () => {
     );
 
     expect(result.current.state.draft.itemsSelector).toBe('a[href]');
+    expect(result.current.suggestion.items).toEqual([]);
 
     await waitFor(() => expect(callsTo(fetchMock, '/feeds/suggest_selectors')).toHaveLength(1));
     const suggestInput = callsTo(fetchMock, '/feeds/suggest_selectors')[0]?.[0];
@@ -367,24 +417,44 @@ describe('useStudio', () => {
     });
 
     await act(async () => {
-      pendingSuggestion.resolve(Response.json(suggestionBody(true, '.post')));
+      pendingSuggestion.resolve(
+        Response.json(
+          rankedSuggestionBody({
+            items: [
+              { selector: '.post', enhance: true },
+              { selector: 'article', enhance: false },
+            ],
+            title: [{ selector: 'h2' }],
+            link: [{ selector: 'a' }],
+            published: [{ selector: 'time' }],
+          })
+        )
+      );
     });
 
-    await waitFor(() => expect(result.current.suggestion?.itemsSelector).toBe('.post'));
-    expect(result.current.suggestion?.enhance).toBe(true);
+    await waitFor(() => expect(result.current.suggestion.items[0]?.selector).toBe('.post'));
+    expect(result.current.suggestion.items).toEqual([
+      { selector: '.post', enhance: true },
+      { selector: 'article', enhance: false },
+    ]);
+    expect(result.current.suggestion.title).toEqual([{ selector: 'h2' }]);
+    expect(result.current.suggestion.link).toEqual([{ selector: 'a' }]);
+    expect(result.current.suggestion.published).toEqual([{ selector: 'time' }]);
     expect(result.current.state.draft.itemsSelector).toBe('a[href]');
     expect(result.current.state.draft.enhance).toBe(false);
+    expect(result.current.state.draft.fields.title.selector).toBe('');
     expect(callsTo(fetchMock, '/feeds/suggest_selectors')).toHaveLength(1);
 
     act(() => {
-      result.current.acceptSuggestion();
+      result.current.applyItemsCandidate({ selector: '.post', enhance: true });
     });
 
     expect(result.current.state.draft.itemsSelector).toBe('.post');
     expect(result.current.state.draft.enhance).toBe(true);
+    expect(result.current.state.draft.fields.title.selector).toBe('');
   });
 
-  it('keeps a typed items selector while still exposing the suggestion', async () => {
+  it('keeps a typed items selector while still exposing candidates', async () => {
     const pendingSuggestion = Promise.withResolvers<Response>();
     mockStudioFetch(fetchMock, {
       suggest: () => pendingSuggestion.promise,
@@ -403,7 +473,7 @@ describe('useStudio', () => {
       pendingSuggestion.resolve(Response.json(suggestionBody(true, '.post')));
     });
 
-    await waitFor(() => expect(result.current.suggestion?.itemsSelector).toBe('.post'));
+    await waitFor(() => expect(result.current.suggestion.items[0]?.selector).toBe('.post'));
     expect(result.current.state.draft.itemsSelector).toBe('article.mine');
     expect(result.current.state.draft.enhance).toBe(false);
     expect(callsTo(fetchMock, '/feeds/suggest_selectors')).toHaveLength(1);
@@ -439,16 +509,25 @@ describe('useStudio', () => {
     expect(live.sample.items[1]?.imageUrl).toBeUndefined();
   });
 
-  it('applies one stored suggestion onto the items selector when accepted', async () => {
+  it('applies only the clicked items candidate onto the draft', async () => {
     mockStudioFetch(fetchMock, {
-      suggest: () => Response.json(suggestionBody(true, '.post')),
+      suggest: () =>
+        Response.json(
+          rankedSuggestionBody({
+            items: [
+              { selector: '.post', enhance: true },
+              { selector: 'article', enhance: false },
+            ],
+            title: [{ selector: 'h2' }],
+          })
+        ),
       preview: () => Response.json(previewBody([], { quality_report: wireNull })),
     });
 
     const { result } = renderHook(() =>
       useStudio({ url: pageUrl, token, validateDelayMs: 0, previewSettleMs: 60_000 })
     );
-    await waitFor(() => expect(result.current.suggestion?.itemsSelector).toBe('.post'));
+    await waitFor(() => expect(result.current.suggestion.items).toHaveLength(2));
 
     act(() => {
       result.current.setItemsSelector('article.bad');
@@ -458,11 +537,38 @@ describe('useStudio', () => {
     expect(result.current.state.draft.enhance).toBe(false);
 
     act(() => {
-      result.current.acceptSuggestion();
+      result.current.applyItemsCandidate({ selector: '.post', enhance: true });
     });
 
     expect(result.current.state.draft.itemsSelector).toBe('.post');
     expect(result.current.state.draft.enhance).toBe(true);
+    expect(result.current.state.draft.fields.title.selector).toBe('');
+    expect(result.current.suggestion.title).toEqual([{ selector: 'h2' }]);
+  });
+
+  it('applies only the clicked field candidate', async () => {
+    mockStudioFetch(fetchMock, {
+      suggest: () =>
+        Response.json(
+          rankedSuggestionBody({
+            items: [{ selector: 'article', enhance: false }],
+            title: [{ selector: 'h2' }, { selector: 'h1' }],
+          })
+        ),
+      preview: () => Response.json(previewBody([], { quality_report: wireNull })),
+    });
+
+    const { result } = renderHook(() =>
+      useStudio({ url: pageUrl, token, validateDelayMs: 0, previewSettleMs: 60_000 })
+    );
+    await waitFor(() => expect(result.current.suggestion.title).toHaveLength(2));
+
+    act(() => {
+      result.current.applyFieldCandidate('title', { selector: 'h2' });
+    });
+
+    expect(result.current.state.draft.fields.title.selector).toBe('h2');
+    expect(result.current.state.draft.itemsSelector).toBe('a[href]');
   });
 
   it('fails closed when validate is unauthorized', async () => {
diff --git a/frontend/src/components/ConfigStudio.tsx b/frontend/src/components/ConfigStudio.tsx
index f2aa1399..e079ec8a 100644
--- a/frontend/src/components/ConfigStudio.tsx
+++ b/frontend/src/components/ConfigStudio.tsx
@@ -5,13 +5,21 @@ import { COPY } from '../journey/copy';
 import { PreviewItem } from './PreviewItem';
 import { Notice } from './Notice';
 import {
-  isDraftMatchingItemsSuggestion,
   issuePlace,
   STUDIO_FIELDS,
+  unusedFieldCandidates,
+  unusedItemsCandidates,
+  type StudioDraft,
   type StudioFieldId,
 } from '../studio/selectorDraft';
 import { canSaveStudio, studioIssues, useStudio, type StudioState } from '../studio/useStudio';
-import type { StudioIssue, StudioSampleItem, StudioSuggestion } from '../studio/studioService';
+import type {
+  StudioFieldCandidate,
+  StudioIssue,
+  StudioItemsCandidate,
+  StudioSampleItem,
+  StudioSuggestion,
+} from '../studio/studioService';
 
 /** Settle delay before URL edits re-trigger suggest / validate / preview. */
 export const STUDIO_URL_SETTLE_MS = 400;
@@ -59,8 +67,6 @@ export function ConfigStudio(properties: ConfigStudioProperties) {
   const ready = state.live.status === 'ready' ? state.live.sample : undefined;
   const nativeFeedUrl = ready?.nativeFeedUrl;
   const isBusy = state.phase === 'validating' || state.phase === 'saving' || state.live.status === 'loading';
-  const isShowSuggestion =
-    suggestion !== undefined && !isDraftMatchingItemsSuggestion(state.draft, suggestion);
 
   useEffect(() => {
     setUrlDraft(url);
@@ -161,9 +167,12 @@ export function ConfigStudio(properties: ConfigStudioProperties) {
         <FieldErrors messages={messagesFor(issues, (issue) => issuePlace(issue.path).kind === 'items')} />
       </label>
 
-      {isShowSuggestion && suggestion ? (
-        <SuggestionChip suggestion={suggestion} onAccept={studio.acceptSuggestion} />
-      ) : undefined}
+      <CandidateChoices
+        draft={state.draft}
+        suggestion={suggestion}
+        onUseItems={studio.applyItemsCandidate}
+        onUseField={studio.applyFieldCandidate}
+      />
 
       <div class="refine-enhance">
         <label class="refine-enhance__label" htmlFor="studio-enhance">
@@ -300,22 +309,102 @@ export function ConfigStudio(properties: ConfigStudioProperties) {
   );
 }
 
-function SuggestionChip({
+function CandidateChoices({
+  draft,
   suggestion,
-  onAccept,
+  onUseItems,
+  onUseField,
 }: {
+  readonly draft: StudioDraft;
   readonly suggestion: StudioSuggestion;
-  readonly onAccept: () => void;
+  readonly onUseItems: (candidate: StudioItemsCandidate) => void;
+  readonly onUseField: (field: StudioFieldId, candidate: StudioFieldCandidate) => void;
 }) {
+  const items = unusedItemsCandidates(draft, suggestion.items);
+  const title = unusedFieldCandidates(draft, 'title', suggestion.title);
+  const link = unusedFieldCandidates(draft, 'link', suggestion.link);
+  const published = unusedFieldCandidates(draft, 'published', suggestion.published);
+  if (items.length === 0 && title.length === 0 && link.length === 0 && published.length === 0) {
+    return;
+  }
+
   return (
-    <div class="refine-suggestion" role="group" aria-label={COPY.suggestedSelectorLabel}>
-      <p class="refine-suggestion__text">
-        <span>{COPY.suggestedSelectorLabel}</span>{' '}
-        <code class="input--mono refine-suggestion__selector">{suggestion.itemsSelector}</code>
-      </p>
-      <button type="button" class="btn btn--quiet" onClick={onAccept}>
-        {COPY.useSuggestion}
-      </button>
+    <div class="refine-candidates" role="group" aria-label={COPY.selectorChoices}>
+      <CandidateBucket
+        heading={COPY.itemsSelector}
+        label={COPY.choicesFor(COPY.itemsSelector)}
+        choices={items.map((candidate) => ({
+          key: `items:${candidate.selector}:${candidate.enhance ? '1' : '0'}`,
+          selector: candidate.selector,
+          enhance: candidate.enhance,
+          onUse: () => onUseItems(candidate),
+        }))}
+      />
+      <CandidateBucket
+        heading={COPY.fieldTitle}
+        label={COPY.choicesFor(COPY.fieldTitle)}
+        choices={title.map((candidate) => ({
+          key: `title:${candidate.selector}`,
+          selector: candidate.selector,
+          onUse: () => onUseField('title', candidate),
+        }))}
+      />
+      <CandidateBucket
+        heading={COPY.fieldLink}
+        label={COPY.choicesFor(COPY.fieldLink)}
+        choices={link.map((candidate) => ({
+          key: `link:${candidate.selector}`,
+          selector: candidate.selector,
+          onUse: () => onUseField('link', candidate),
+        }))}
+      />
+      <CandidateBucket
+        heading={COPY.fieldPublished}
+        label={COPY.choicesFor(COPY.fieldPublished)}
+        choices={published.map((candidate) => ({
+          key: `published:${candidate.selector}`,
+          selector: candidate.selector,
+          onUse: () => onUseField('published', candidate),
+        }))}
+      />
+    </div>
+  );
+}
+
+function CandidateBucket({
+  heading,
+  label,
+  choices,
+}: {
+  readonly heading: string;
+  readonly label: string;
+  readonly choices: readonly {
+    readonly key: string;
+    readonly selector: string;
+    readonly enhance?: boolean;
+    readonly onUse: () => void;
+  }[];
+}) {
+  if (choices.length === 0) return;
+
+  return (
+    <div class="refine-candidates__bucket" role="group" aria-label={label}>
+      <p class="ui-eyebrow">{heading}</p>
+      <ul class="refine-candidates__list">
+        {choices.map((choice) => (
+          <li key={choice.key} class="refine-suggestion">
+            <p class="refine-suggestion__text">
+              <code class="input--mono refine-suggestion__selector">{choice.selector}</code>
+              {choice.enhance ? (
+                <span class="field-help refine-suggestion__enhance">{COPY.enhanceItems}</span>
+              ) : undefined}
+            </p>
+            <button type="button" class="btn btn--quiet" onClick={choice.onUse}>
+              {COPY.useSuggestion}
+            </button>
+          </li>
+        ))}
+      </ul>
     </div>
   );
 }
diff --git a/frontend/src/journey/copy.ts b/frontend/src/journey/copy.ts
index d564de03..6f27a2a5 100644
--- a/frontend/src/journey/copy.ts
+++ b/frontend/src/journey/copy.ts
@@ -70,7 +70,9 @@ export const COPY = {
   previewRegion: 'Feed preview',
   itemsSelector: 'Items selector',
   enhanceItems: 'Enhance items',
-  suggestedSelectorLabel: 'Suggested:',
+  /** Ranked refine choices; buckets may be empty. */
+  selectorChoices: 'Selector choices',
+  choicesFor: (name: string) => `${name} options`,
   useSuggestion: 'Use',
   saveAndGenerate: 'Save and generate feed',
   viewAsYaml: 'View as YAML',
diff --git a/frontend/src/studio/selectorDraft.ts b/frontend/src/studio/selectorDraft.ts
index 2ec6154f..efe5f2d6 100644
--- a/frontend/src/studio/selectorDraft.ts
+++ b/frontend/src/studio/selectorDraft.ts
@@ -100,12 +100,36 @@ export function applyItemsSuggestion(
   return { ...draft, itemsSelector, enhance: isEnhanced };
 }
 
-/** True when the authored draft already matches the server suggestion (chip has nothing to apply). */
-export function isDraftMatchingItemsSuggestion(
+/** True when the authored draft already matches this items candidate (hide that Use row). */
+export function isDraftMatchingItemsCandidate(
   draft: StudioDraft,
-  suggestion: { readonly itemsSelector: string; readonly enhance: boolean }
+  candidate: { readonly selector: string; readonly enhance: boolean }
 ): boolean {
-  return draft.itemsSelector === suggestion.itemsSelector && draft.enhance === suggestion.enhance;
+  return draft.itemsSelector === candidate.selector && draft.enhance === candidate.enhance;
+}
+
+/** True when the authored field selector already matches this candidate (hide that Use row). */
+export function isDraftMatchingFieldCandidate(
+  draft: StudioDraft,
+  field: StudioFieldId,
+  candidate: { readonly selector: string }
+): boolean {
+  return draft.fields[field].selector === candidate.selector;
+}
+
+export function unusedItemsCandidates<T extends { readonly selector: string; readonly enhance: boolean }>(
+  draft: StudioDraft,
+  candidates: readonly T[]
+): readonly T[] {
+  return candidates.filter((candidate) => !isDraftMatchingItemsCandidate(draft, candidate));
+}
+
+export function unusedFieldCandidates<T extends { readonly selector: string }>(
+  draft: StudioDraft,
+  field: StudioFieldId,
+  candidates: readonly T[]
+): readonly T[] {
+  return candidates.filter((candidate) => !isDraftMatchingFieldCandidate(draft, field, candidate));
 }
 
 export function issuePlace(path: readonly string[]): IssuePlace {
diff --git a/frontend/src/studio/studioService.ts b/frontend/src/studio/studioService.ts
index 848f3834..d44edfb1 100644
--- a/frontend/src/studio/studioService.ts
+++ b/frontend/src/studio/studioService.ts
@@ -1,8 +1,8 @@
 /**
  * Studio transport. The only place the `{ success, data }` envelope is unwrapped.
  *
- * Issue codes are the generated client's closed union. Selector documents map
- * through {@link StudioDraft} at this boundary.
+ * Issue codes are the generated client's closed union. Selector documents and
+ * ranked suggestion candidates map through domain types at this boundary.
  */
 import type { RefinedSelectorsDocument, ValidateFeedConfigResponses } from '../api/generated';
 import type { HttpEnvelope } from '../api/http/client';
@@ -41,11 +41,35 @@ export interface StudioPreview {
   readonly failureKind: string | undefined;
 }
 
-export interface StudioSuggestion {
-  readonly itemsSelector: string;
+/** One ranked items selector. Best match is first in the bucket. */
+export interface StudioItemsCandidate {
+  readonly selector: string;
   readonly enhance: boolean;
 }
 
+/** One ranked field selector. Best match is first in the bucket. */
+export interface StudioFieldCandidate {
+  readonly selector: string;
+}
+
+/**
+ * Ranked suggestion buckets from suggest_selectors. Empty buckets are success.
+ * Wire `data.candidates` maps here — never leak generated OpenAPI types to UI.
+ */
+export interface StudioSuggestion {
+  readonly items: readonly StudioItemsCandidate[];
+  readonly title: readonly StudioFieldCandidate[];
+  readonly link: readonly StudioFieldCandidate[];
+  readonly published: readonly StudioFieldCandidate[];
+}
+
+export const EMPTY_STUDIO_SUGGESTION: StudioSuggestion = {
+  items: [],
+  title: [],
+  link: [],
+  published: [],
+};
+
 export class StudioRequestError extends Error {
   constructor(message: string) {
     super(message);
@@ -230,21 +254,50 @@ function parseFailureKind(value: unknown): string | undefined {
 }
 
 function parseSuggestion(data: unknown): StudioSuggestion {
-  if (!isPlainRecord(data)) throw new StudioRequestError(COPY.unableToCompleteCreation);
-
-  const draft = isAbsent(data.selectors) ? undefined : draftFromSelectors(data.selectors);
-  if (data.selectors !== undefined && !isAbsent(data.selectors) && !draft) {
+  if (!isPlainRecord(data) || !isPlainRecord(data.candidates)) {
     throw new StudioRequestError(COPY.unableToCompleteCreation);
   }
 
-  const enhance = typeof data.enhance === 'boolean' ? data.enhance : (draft?.enhance ?? false);
+  const buckets = data.candidates;
+  return {
+    items: parseItemsCandidates(buckets.items),
+    title: parseFieldCandidates(buckets.title),
+    link: parseFieldCandidates(buckets.link),
+    published: parseFieldCandidates(buckets.published),
+  };
+}
 
+function parseItemsCandidates(value: unknown): readonly StudioItemsCandidate[] {
+  if (!Array.isArray(value)) throw new StudioRequestError(COPY.unableToCompleteCreation);
+  return value.map((entry) => parseItemsCandidate(entry));
+}
+
+function parseItemsCandidate(value: unknown): StudioItemsCandidate {
+  if (!isPlainRecord(value) || typeof value.selector !== 'string') {
+    throw new StudioRequestError(COPY.unableToCompleteCreation);
+  }
+  const selector = value.selector.trim();
+  if (selector.length === 0) throw new StudioRequestError(COPY.unableToCompleteCreation);
   return {
-    itemsSelector: draft?.itemsSelector ?? '',
-    enhance,
+    selector,
+    enhance: value.enhance === true,
   };
 }
 
+function parseFieldCandidates(value: unknown): readonly StudioFieldCandidate[] {
+  if (!Array.isArray(value)) throw new StudioRequestError(COPY.unableToCompleteCreation);
+  return value.map((entry) => parseFieldCandidate(entry));
+}
+
+function parseFieldCandidate(value: unknown): StudioFieldCandidate {
+  if (!isPlainRecord(value) || typeof value.selector !== 'string') {
+    throw new StudioRequestError(COPY.unableToCompleteCreation);
+  }
+  const selector = value.selector.trim();
+  if (selector.length === 0) throw new StudioRequestError(COPY.unableToCompleteCreation);
+  return { selector };
+}
+
 function isAbsent(value: unknown): boolean {
   return value === undefined || value === null;
 }
diff --git a/frontend/src/studio/useStudio.ts b/frontend/src/studio/useStudio.ts
index 188c0b87..a908fcec 100644
--- a/frontend/src/studio/useStudio.ts
+++ b/frontend/src/studio/useStudio.ts
@@ -2,11 +2,14 @@ import { useEffect, useRef, useState } from 'preact/hooks';
 import { isAbortError, isFeedCreationError } from '../feeds/feedsService';
 import { COPY } from '../journey/copy';
 import {
+  EMPTY_STUDIO_SUGGESTION,
   previewStudioFeed,
   StudioRequestError,
   suggestStudioSelectors,
   validateStudioSelectors,
+  type StudioFieldCandidate,
   type StudioIssue,
+  type StudioItemsCandidate,
   type StudioPreview,
   type StudioSuggestion,
   type StudioValidationOutcome,
@@ -68,7 +71,7 @@ export function useStudio({
     validated: false,
     live: { status: 'idle' },
   });
-  const [suggestion, setSuggestion] = useState<StudioSuggestion | undefined>(undefined);
+  const [suggestion, setSuggestion] = useState<StudioSuggestion>(EMPTY_STUDIO_SUGGESTION);
   const [documentRevision, setDocumentRevision] = useState(0);
 
   const stateReference = useRef(state);
@@ -254,12 +257,16 @@ export function useStudio({
     }
   }
 
-  function acceptSuggestion() {
-    const current = suggestion;
-    if (!current) return;
+  /** Apply only the clicked items candidate — never auto-applied on suggest. */
+  function applyItemsCandidate(candidate: StudioItemsCandidate) {
     itemsTouchedReference.current = true;
     enhanceTouchedReference.current = true;
-    editSelectors((draft) => applyItemsSuggestion(draft, current.itemsSelector, current.enhance));
+    editSelectors((draft) => applyItemsSuggestion(draft, candidate.selector, candidate.enhance));
+  }
+
+  /** Apply only the clicked field candidate — extractors stay fixed by the draft mapper. */
+  function applyFieldCandidate(field: StudioFieldId, candidate: StudioFieldCandidate) {
+    editSelectors((draft) => withFieldSelector(draft, field, candidate.selector));
   }
 
   function retryPreview() {
@@ -295,7 +302,8 @@ export function useStudio({
     setItemsSelector,
     setEnhance,
     setFieldSelector,
-    acceptSuggestion,
+    applyItemsCandidate,
+    applyFieldCandidate,
     requestSuggestion: () => {
       void requestSuggestion();
     },
diff --git a/frontend/src/styles/main.css b/frontend/src/styles/main.css
index cfe8b7a3..2e611294 100644
--- a/frontend/src/styles/main.css
+++ b/frontend/src/styles/main.css
@@ -581,6 +581,27 @@
   justify-content: flex-start;
 }
 
+.refine-candidates {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-3);
+}
+
+.refine-candidates__bucket {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-2);
+}
+
+.refine-candidates__list {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-2);
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
 .refine-suggestion {
   display: flex;
   flex-wrap: wrap;
@@ -597,6 +618,10 @@
   word-break: break-all;
 }
 
+.refine-suggestion__enhance {
+  margin-left: var(--space-2);
+}
+
 .refine-enhance {
   display: flex;
   flex-direction: column;

From a006828a9ae02c3be9137a34cd595e531eb98f81 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Mon, 21 Sep 2026 11:11:33 +0200
Subject: [PATCH 066/108] chore(deps): pin selector candidate class fix

---
 Gemfile      | 2 +-
 Gemfile.lock | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Gemfile b/Gemfile
index c282adf0..40144e9e 100644
--- a/Gemfile
+++ b/Gemfile
@@ -8,7 +8,7 @@ git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
 # Config::IssueMapper, and CaptureResult#candidates, which no released 0.30.x
 # gem carries. Bump this ref deliberately; do not swap it for `branch:` or for
 # a rubygems version constraint.
-gem 'html2rss', github: 'html2rss/html2rss', ref: '8890cd37090b2f56c00ce8973a6c892517c14986'
+gem 'html2rss', github: 'html2rss/html2rss', ref: '94cd977492b5600b55d98361e1b56b82b08378a4'
 gem 'html2rss-configs', github: 'html2rss/html2rss-configs'
 
 # Use these instead of the two above (uncomment them) when developing locally:
diff --git a/Gemfile.lock b/Gemfile.lock
index becfc1bd..717f29a7 100644
--- a/Gemfile.lock
+++ b/Gemfile.lock
@@ -1,7 +1,7 @@
 GIT
   remote: https://github.com/html2rss/html2rss
-  revision: 8890cd37090b2f56c00ce8973a6c892517c14986
-  ref: 8890cd37090b2f56c00ce8973a6c892517c14986
+  revision: 94cd977492b5600b55d98361e1b56b82b08378a4
+  ref: 94cd977492b5600b55d98361e1b56b82b08378a4
   specs:
     html2rss (0.30.0)
       addressable (~> 2.7)

From 178ce3a0acde1d609b6ee3d81759407f08c4b5fe Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Mon, 21 Sep 2026 13:04:54 +0200
Subject: [PATCH 067/108] chore(deps): pin html2rss to rebased selector
 candidates

The candidates branch now includes the Falcon HTTPX retry fix from master.
---
 Gemfile      | 9 ++++-----
 Gemfile.lock | 4 ++--
 2 files changed, 6 insertions(+), 7 deletions(-)

diff --git a/Gemfile b/Gemfile
index 40144e9e..888126d5 100644
--- a/Gemfile
+++ b/Gemfile
@@ -4,11 +4,10 @@ source 'https://rubygems.org'
 
 git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
 
-# Pinned by revision, not by branch: the studio needs the gsub pattern bounds,
-# Config::IssueMapper, and CaptureResult#candidates, which no released 0.30.x
-# gem carries. Bump this ref deliberately; do not swap it for `branch:` or for
-# a rubygems version constraint.
-gem 'html2rss', github: 'html2rss/html2rss', ref: '94cd977492b5600b55d98361e1b56b82b08378a4'
+# Pinned by revision, not by branch. This ref is feat/suggest-selector-candidates
+# rebased onto master, so it includes CaptureResult#candidates and the Falcon/HTTPX
+# retry fix. Bump it deliberately; do not swap it for `branch:` or a rubygems constraint.
+gem 'html2rss', github: 'html2rss/html2rss', ref: '281e5e9053f102171bc24d2d7dc018fe4c1871cb'
 gem 'html2rss-configs', github: 'html2rss/html2rss-configs'
 
 # Use these instead of the two above (uncomment them) when developing locally:
diff --git a/Gemfile.lock b/Gemfile.lock
index 717f29a7..37b648f0 100644
--- a/Gemfile.lock
+++ b/Gemfile.lock
@@ -1,7 +1,7 @@
 GIT
   remote: https://github.com/html2rss/html2rss
-  revision: 94cd977492b5600b55d98361e1b56b82b08378a4
-  ref: 94cd977492b5600b55d98361e1b56b82b08378a4
+  revision: 281e5e9053f102171bc24d2d7dc018fe4c1871cb
+  ref: 281e5e9053f102171bc24d2d7dc018fe4c1871cb
   specs:
     html2rss (0.30.0)
       addressable (~> 2.7)

From 579e0eb1979a952c2a0e5af0c8f02f6e028c9481 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Mon, 21 Sep 2026 13:04:54 +0200
Subject: [PATCH 068/108] feat(dev): start the local app with published
 Botasaurus

make up runs this checkout plus the scraper image on loopback. The macOS
port check uses lsof so Falcon is not killed after boot.
---
 Makefile                      | 14 +++++++++++++-
 bin/dev                       | 19 +++++++++++++++++--
 docker-compose.botasaurus.yml | 11 +++++++++++
 3 files changed, 41 insertions(+), 3 deletions(-)
 create mode 100644 docker-compose.botasaurus.yml

diff --git a/Makefile b/Makefile
index 789dac75..eb6cd2af 100644
--- a/Makefile
+++ b/Makefile
@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
-.PHONY: help test lint lint-js lint-ruby lintfix lintfix-js lintfix-ruby setup dev clean frontend-setup check-frontend quick-check ready ci-ready yard-verify-public-docs openapi openapi-verify openapi-client openapi-client-verify openapi-lint openapi-lint-redocly openapi-lint-spectral openai-lint-spectral test-frontend-e2e lint-css-primitives
+.PHONY: help test lint lint-js lint-ruby lintfix lintfix-js lintfix-ruby setup dev up down clean frontend-setup check-frontend quick-check ready ci-ready yard-verify-public-docs openapi openapi-verify openapi-client openapi-client-verify openapi-lint openapi-lint-redocly openapi-lint-spectral openai-lint-spectral test-frontend-e2e lint-css-primitives
+
+# Host-side local app. Distinct project so this does not stop the published web stack.
+DEV_COMPOSE = docker compose -p html2rss-dev -f docker-compose.botasaurus.yml
 
 RUBOCOP_FLAGS ?= --cache false
 
@@ -26,6 +29,15 @@ dev: ## Start development server with live reload
 	@echo "Starting html2rss-web development environment..."
 	@bin/dev
 
+up: ## Local web app (this checkout) plus published Botasaurus
+	$(DEV_COMPOSE) up -d
+	BOTASAURUS_SCRAPER_URL=http://127.0.0.1:4010 bin/dev
+
+down: ## Stop the local web app and published Botasaurus
+	-pkill -f "falcon.*html2rss-web" || true
+	-pkill -f "vite.*4001" || true
+	$(DEV_COMPOSE) down
+
 dev-ruby: ## Start Ruby server only
 	@bin/dev-ruby
 
diff --git a/bin/dev b/bin/dev
index a65b8bf1..1d1c68a1 100755
--- a/bin/dev
+++ b/bin/dev
@@ -3,16 +3,31 @@
 
 set -e
 
+# Caller wins (make up sets the host loopback URL). .env must not clobber it.
+preset_botasaurus_url="${BOTASAURUS_SCRAPER_URL-}"
+
 # Load .env if exists
 if [ -f .env ]; then
   export $(cat .env | grep -v '^#' | xargs)
 fi
 
+if [ -n "$preset_botasaurus_url" ]; then
+  export BOTASAURUS_SCRAPER_URL="$preset_botasaurus_url"
+fi
+
 export RACK_ENV=${RACK_ENV:-development}
 
-# BusyBox lsof in this image reports internal FDs and exits 0, so prefer netstat.
+# BusyBox lsof reports internal FDs and exits 0, so the container keeps Linux netstat.
+# macOS netstat has no -l listening flag, so the same check never sees port 4000.
 port_in_use() {
-  netstat -ltn 2>/dev/null | awk '{print $4}' | grep -Eq "[:.]$1$"
+  case "$(uname -s)" in
+    Darwin)
+      lsof -nP -iTCP:"$1" -sTCP:LISTEN >/dev/null 2>&1
+      ;;
+    *)
+      netstat -ltn 2>/dev/null | awk '{print $4}' | grep -Eq "[:.]$1$"
+      ;;
+  esac
 }
 
 # Cleanup function for graceful shutdown
diff --git a/docker-compose.botasaurus.yml b/docker-compose.botasaurus.yml
new file mode 100644
index 00000000..6ee840bb
--- /dev/null
+++ b/docker-compose.botasaurus.yml
@@ -0,0 +1,11 @@
+# Published scraper for local `make up`. The web app stays on the host via bin/dev.
+services:
+  botasaurus:
+    image: html2rss/botasaurus-scrape-api:latest
+    restart: unless-stopped
+    environment:
+      SENTRY_DSN: ${BOTASAURUS_SENTRY_DSN:-}
+      SCRAPE_TIMEOUT_SECONDS: 45
+      SCRAPE_WORK_TIMEOUT_SECONDS: 30
+    ports:
+      - "127.0.0.1:4010:4010"

From 37f12e22b35124837670c6c399124582a9b7aaf6 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Mon, 21 Sep 2026 13:55:29 +0200
Subject: [PATCH 069/108] feat(refine): toggle selector parts with chips

Chips add or remove comma-separated parts on the authored selector string. Suggest still does not write the draft, and chips do not change Enhance.
---
 CONTEXT.md                                   |   2 +-
 docs/design-system.md                        |   4 +-
 frontend/e2e/smoke.spec.ts                   |  12 +-
 frontend/src/__tests__/App.contract.test.tsx |  19 ++-
 frontend/src/__tests__/ConfigStudio.test.tsx | 104 ++++++++++------
 frontend/src/__tests__/selectorDraft.test.ts |  51 ++++++++
 frontend/src/__tests__/useStudio.test.ts     |  54 +++++----
 frontend/src/components/ConfigStudio.tsx     | 121 +++++++++----------
 frontend/src/journey/copy.ts                 |   3 +-
 frontend/src/studio/selectorDraft.ts         | 119 +++++++++++++-----
 frontend/src/studio/useStudio.ts             |  23 ++--
 frontend/src/styles/main.css                 |  34 +++---
 12 files changed, 352 insertions(+), 194 deletions(-)
 create mode 100644 frontend/src/__tests__/selectorDraft.test.ts

diff --git a/CONTEXT.md b/CONTEXT.md
index 707e76a9..60027b43 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -29,7 +29,7 @@ On create, `findCatalogEntries` matches the typed query against the catalog (URL
 Visiting create (including hashbang `#!/…` → `#/…`) bumps `createEntryKey` so the create surface remounts. Remount alone does not auto-submit; auto-submit requires `prefillUrl`.
 
 ### Config Studio
-Selector refinement for a token holder when studio is enabled. On a successful result, refinement is available on demand behind demoted **Refine selectors** on `#/result/:token` (collapsed by default; one meadow; live studio output replaces the result preview when expanded). `#/refine` is only extraction-empty recovery when no result exists. Memory-bound to the in-memory page URL (no token in the route). The visual builder and YAML are one document; only `studioService` unwraps the studio envelope and maps ranked `candidates` (items / title / link / published) into domain suggestion buckets. Candidates never auto-apply — each **Use** applies only that clicked choice; rows already matching the draft stay hidden. Field extractors remain fixed by the draft mapper. Save posts refined selectors through Creation IO and stays on the result view.
+Selector refinement for a token holder when studio is enabled. On a successful result, refinement is available on demand behind demoted **Refine selectors** on `#/result/:token` (collapsed by default; one meadow; live studio output replaces the result preview when expanded). `#/refine` is only extraction-empty recovery when no result exists. Memory-bound to the in-memory page URL (no token in the route). The visual builder and YAML are one document; only `studioService` unwraps the studio envelope and maps ranked `candidates` (items / title / link / published) into domain suggestion buckets. Candidates never auto-apply. Chips add or remove selector parts on the authored comma-joined string; suggest does not write that string, and chips do not change Enhance. Field extractors remain fixed by the draft mapper. Save posts refined selectors through Creation IO and stays on the result view.
 
 ### Refined Selectors
 The allowlisted `selectors` document a token holder may attach on feed creation. Signed into the feed token and resolved on later serves. Not a full config: channel, headers, and strategy stay denied.
diff --git a/docs/design-system.md b/docs/design-system.md
index 40d1a1e8..c16b53e6 100644
--- a/docs/design-system.md
+++ b/docs/design-system.md
@@ -42,7 +42,7 @@ If a page looks like it came from a different product, the change is wrong even
 - **Token gate:** a native `<dialog>` over the still-mounted, inert URL task (one interactive task). Auth copy is in-field (`tokenError`); ActionFeedback stays on create. Access Token persists until Logout with no storage UI.
 - **Result:** primary CTA is **Copy feed URL**, and it takes initial focus. Open feed / JSON / feed-reader are demoted secondary actions and stay available while preview loads. Preview is one meadow and non-blocking confirmation only. Guest results stay compact: at most 5 items, no images, no selector controls. An authenticated, studio-enabled result keeps that same frame: a demoted **Refine selectors** action in `ui-actions` (collapsed by default). Opening it mounts selector controls **above** the meadow; closing it returns to the static meadow without discarding the in-memory draft. Studio validate/preview/suggest do not run until the panel opens. Selector edits replace the meadow with live studio output; they do not add a second list. **Save and generate feed** is the only primary action inside those controls. Member previews may show up to 10 items and safe HTTP(S) images.
 - **Empty extraction:** **Refine selectors** is one quiet action beside Try again when the extraction is empty, studio is enabled, and an access token is present. It is not offered for other create errors, guests, or a studio-off instance.
-- **Refine:** `#/refine` is memory-bound extraction-empty recovery for an authenticated studio (see [personas.md](personas.md) J2). No token in the route. A successful in-memory result replaces `#/refine` with `#/result/:token`; refinement of that feed stays on the result behind the same demoted **Refine selectors** gate. Standalone recovery uses the same frame as an expanded Result: a `result-shell` / `layout-stack` rail — never a mega-card bisected by the fixed footer, never a two-column paddock. First viewport leads with compact controls (items selector, ranked **Selector choices** per bucket with explicit **Use** actions, a large Enhance hit target, and **Save and generate feed** as the only `btn--primary` in `ui-actions`), then the live preview meadow (`.ui-item-list`) after validation. URL, native-feed Notice, and View as YAML are demoted support below the meadow. Changing the URL re-suggests and re-previews without leaving the current surface or running catalog find; empty URL recovers onto remounted `#/create`. Ranked candidates (items, title, link, published) stay separate from the authored draft until the user clicks **Use** on one row; that click applies only that candidate, and rows already matching the draft are hidden. Empty buckets stay hidden. Wire is the typed closed selectors document (no strip/trim/affix cleanup UI). Fix a field opens one selector panel **in the stack** for Title, Link, or Published date. View as YAML is read-only and captioned as a selectors fragment — not a feeds.yml. Save-failure Notices use wire `Decision#message` — never create-journey copy. When studio is disabled or the caller has no token, Refine actions stay hidden and `#/refine` bounces to create. Focus on standalone recovery is the items selector; a successful Result keeps focus on Copy whether Refine is open or closed.
+- **Refine:** `#/refine` is memory-bound extraction-empty recovery for an authenticated studio (see [personas.md](personas.md) J2). No token in the route. A successful in-memory result replaces `#/refine` with `#/result/:token`; refinement of that feed stays on the result behind the same demoted **Refine selectors** gate. Standalone recovery uses the same frame as an expanded Result: a `result-shell` / `layout-stack` rail — never a mega-card bisected by the fixed footer, never a two-column paddock. First viewport leads with compact controls (items selector, ranked **Selector choices** per bucket as wrapping add/remove chips, a large Enhance hit target, and **Save and generate feed** as the only `btn--primary` in `ui-actions`), then the live preview meadow (`.ui-item-list`) after validation. URL, native-feed Notice, and View as YAML are demoted support below the meadow. Changing the URL re-suggests and re-previews without leaving the current surface or running catalog find; empty URL recovers onto remounted `#/create`. Ranked candidates (items, title, link, published) are wrapping chips on the authored selector. A chip adds or removes its selector parts in the comma-joined draft string; suggest does not write that string. Chips do not change Enhance. Empty buckets stay hidden. Wire is the typed closed selectors document (no strip/trim/affix cleanup UI). Fix a field opens one selector panel **in the stack** for Title, Link, or Published date. View as YAML is read-only and captioned as a selectors fragment — not a feeds.yml. Save-failure Notices use wire `Decision#message` — never create-journey copy. When studio is disabled or the caller has no token, Refine actions stay hidden and `#/refine` bounces to create. Focus on standalone recovery is the items selector; a successful Result keeps focus on Copy whether Refine is open or closed.
 - **Unmatched result:** `#/result/:token` is valid only with a matching in-memory result. Missing or mismatched tokens recover onto remounted `#/create` (no API rehydrate, no failure chrome, no durable shareable result page).
 - **Status eyebrow:** one vocabulary (`Feed ready`) on the result header; preview progress lives in the preview section.
 - **Focus:** create autofocuses the URL field; token autofocuses the token field; result focuses the Copy control; standalone extraction-empty refine focuses the items selector.
@@ -55,7 +55,7 @@ If a page looks like it came from a different product, the change is wrong even
 | Output | **Feed URL** |
 | Create | **Create feed** / **Creating feed** |
 | Result | **Feed ready** / **Copy feed URL** |
-| Refine | **Refine selectors** / **Selector choices** / **Use** / **Save and generate feed** / **View as YAML** |
+| Refine | **Refine selectors** / **Selector choices** / **Add** / **Remove** / **Save and generate feed** / **View as YAML** |
 | Retry | **Try again** (button only) |
 | Preview | **Checking preview** / **Check again** |
 | Catalog | **Feed Directory** |
diff --git a/frontend/e2e/smoke.spec.ts b/frontend/e2e/smoke.spec.ts
index e90f83d5..fa417b00 100644
--- a/frontend/e2e/smoke.spec.ts
+++ b/frontend/e2e/smoke.spec.ts
@@ -251,10 +251,14 @@ test.describe('frontend smoke', () => {
       name: COPY.choicesFor(COPY.itemsSelector),
       exact: true,
     });
-    await expect(itemsChoices.getByRole('button', { name: COPY.useSuggestion })).toBeVisible();
-    await itemsChoices.getByRole('button', { name: COPY.useSuggestion }).click();
-    await expect(items).toHaveValue('article');
-    await expect(page.getByRole('group', { name: COPY.selectorChoices, exact: true })).toHaveCount(0);
+    await expect(itemsChoices.getByRole('button', { name: COPY.addSelector('article') })).toBeVisible();
+    await itemsChoices.getByRole('button', { name: COPY.addSelector('article') }).click();
+    await expect(items).toHaveValue('a[href], article');
+    await expect(itemsChoices.getByRole('button', { name: COPY.removeSelector('article') })).toHaveAttribute(
+      'aria-pressed',
+      'true'
+    );
+    await expect(page.getByRole('group', { name: COPY.selectorChoices, exact: true })).toBeVisible();
     await expect(page.getByText('Refine meadow item')).toBeVisible();
     await expect(page.locator('.ui-item-list')).toHaveCount(1);
     const meadow = page.getByLabel(COPY.previewRegion, { exact: true });
diff --git a/frontend/src/__tests__/App.contract.test.tsx b/frontend/src/__tests__/App.contract.test.tsx
index 1f7ee00e..c43258fd 100644
--- a/frontend/src/__tests__/App.contract.test.tsx
+++ b/frontend/src/__tests__/App.contract.test.tsx
@@ -226,12 +226,16 @@ describe('App contract', () => {
     await waitFor(() => {
       expect(itemsSelector).toHaveValue('a[href]');
     });
-    const useSuggestion = await screen.findByRole('button', { name: COPY.useSuggestion });
-    fireEvent.click(useSuggestion);
+    const addArticle = await screen.findByRole('button', { name: COPY.addSelector('article') });
+    fireEvent.click(addArticle);
     await waitFor(() => {
-      expect(itemsSelector).toHaveValue('article');
+      expect(itemsSelector).toHaveValue('a[href], article');
     });
-    expect(screen.queryByRole('button', { name: COPY.useSuggestion })).not.toBeInTheDocument();
+    expect(screen.getByRole('button', { name: COPY.removeSelector('article') })).toHaveAttribute(
+      'aria-pressed',
+      'true'
+    );
+    expect(screen.getByLabelText(COPY.enhanceItems)).not.toBeChecked();
     const save = screen.getByRole('button', { name: COPY.saveAndGenerate });
     await waitFor(() => expect(save).toBeEnabled());
     expect(document.querySelectorAll('.ui-item-list')).toHaveLength(1);
@@ -243,8 +247,8 @@ describe('App contract', () => {
     });
     expect(bodies[1]).toMatchObject({
       url: 'https://example.com/articles',
-      selectors: { items: { selector: 'article', enhance: true } },
     });
+    expect(postedSelectors(bodies[1])).toEqual({ items: { selector: 'a[href], article' } });
     await screen.findByText(COPY.feedReady);
     fetchSpy.mockRestore();
   });
@@ -254,3 +258,8 @@ function readUrl(body: unknown): string | undefined {
   if (!body || typeof body !== 'object' || !('url' in body)) return undefined;
   return typeof body.url === 'string' ? body.url : undefined;
 }
+
+function postedSelectors(body: unknown): unknown {
+  if (!body || typeof body !== 'object' || !('selectors' in body)) return undefined;
+  return body.selectors;
+}
diff --git a/frontend/src/__tests__/ConfigStudio.test.tsx b/frontend/src/__tests__/ConfigStudio.test.tsx
index f3625e16..1e177304 100644
--- a/frontend/src/__tests__/ConfigStudio.test.tsx
+++ b/frontend/src/__tests__/ConfigStudio.test.tsx
@@ -106,18 +106,18 @@ function renderStudio(
   return { onGenerate, onUrlChange, onUrlCleared };
 }
 
-function itemsChoiceUse() {
-  return within(screen.getByRole('group', { name: COPY.choicesFor(COPY.itemsSelector) })).getAllByRole(
+function itemsChip(name = COPY.addSelector('article')) {
+  return within(screen.getByRole('group', { name: COPY.choicesFor(COPY.itemsSelector) })).getByRole(
     'button',
     {
-      name: COPY.useSuggestion,
+      name,
     }
-  )[0]!;
+  );
 }
 
-async function waitForItemsChoiceUse() {
-  await waitFor(() => expect(itemsChoiceUse()).toBeInTheDocument());
-  return itemsChoiceUse();
+async function waitForItemsChip(name = COPY.addSelector('article')) {
+  await waitFor(() => expect(itemsChip(name)).toBeInTheDocument());
+  return itemsChip(name);
 }
 
 describe('ConfigStudio', () => {
@@ -150,7 +150,7 @@ describe('ConfigStudio', () => {
     await waitFor(() => expect(items).toHaveFocus());
     await waitFor(() => expect(items).toHaveValue('a[href]'));
     expect(screen.getByLabelText(COPY.enhanceItems)).toBeInTheDocument();
-    await waitFor(() => expect(itemsChoiceUse()).toBeInTheDocument());
+    await waitFor(() => expect(itemsChip()).toBeInTheDocument());
     expect(screen.getByRole('button', { name: COPY.fieldMissing(COPY.fieldTitle) })).toBeInTheDocument();
     expect(screen.getByRole('button', { name: COPY.fieldMissing(COPY.fieldLink) })).toBeInTheDocument();
     expect(screen.getByRole('button', { name: COPY.fieldMissing(COPY.fieldPublished) })).toBeInTheDocument();
@@ -238,7 +238,10 @@ describe('ConfigStudio', () => {
     expect(screen.getByText('time')).toBeInTheDocument();
     expect(screen.queryByText('list')).not.toBeInTheDocument();
     expect(screen.queryByText(/chrome/)).not.toBeInTheDocument();
-    expect(itemsChoiceUse()).toHaveClass('btn--quiet');
+    const itemsGroup = screen.getByRole('group', { name: COPY.choicesFor(COPY.itemsSelector) });
+    expect(itemsChip()).toHaveClass('refine-chip');
+    expect(itemsChip()).toHaveAttribute('aria-pressed', 'false');
+    expect(within(itemsGroup).queryByText(COPY.enhanceItems)).not.toBeInTheDocument();
     expect(screen.getByRole('button', { name: COPY.saveAndGenerate }).closest('.ui-actions')).not.toBeNull();
   });
 
@@ -255,56 +258,88 @@ describe('ConfigStudio', () => {
     expect(screen.getByLabelText(COPY.enhanceItems)).not.toBeChecked();
   });
 
-  it('applies only the clicked items candidate when Use is pressed', async () => {
+  it('adds and removes selector parts from chips without changing enhance', async () => {
     echoValidate();
     stubSuggest(
       rankedSuggestSuccessBody({
         items: [
-          { selector: '.post', enhance: true },
-          { selector: 'article', enhance: false },
+          { selector: 'article, div', enhance: true },
+          { selector: 'main', enhance: false },
         ],
         title: [{ selector: 'h2' }],
       })
     );
     renderStudio();
-    await waitFor(() => expect(itemsChoiceUse()).toBeInTheDocument());
+    await waitFor(() => expect(itemsChip(COPY.addSelector('article'))).toBeInTheDocument());
 
-    fireEvent.input(screen.getByLabelText(COPY.itemsSelector), { target: { value: 'article.bad' } });
-    expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('article.bad');
-    expect(screen.getByLabelText(COPY.enhanceItems)).not.toBeChecked();
+    fireEvent.input(screen.getByLabelText(COPY.itemsSelector), { target: { value: 'a[href]' } });
+    fireEvent.click(screen.getByLabelText(COPY.enhanceItems));
+    expect(screen.getByLabelText(COPY.enhanceItems)).toBeChecked();
 
     const itemsGroup = screen.getByRole('group', { name: COPY.choicesFor(COPY.itemsSelector) });
-    const useButtons = within(itemsGroup).getAllByRole('button', { name: COPY.useSuggestion });
-    fireEvent.click(useButtons[0]!);
+    fireEvent.click(within(itemsGroup).getByRole('button', { name: COPY.addSelector('article') }));
+    fireEvent.click(within(itemsGroup).getByRole('button', { name: COPY.addSelector('div') }));
+    fireEvent.click(within(itemsGroup).getByRole('button', { name: COPY.addSelector('main') }));
 
-    expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('.post');
+    expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('a[href], article, div, main');
     expect(screen.getByLabelText(COPY.enhanceItems)).toBeChecked();
-    expect(screen.getByText('article')).toBeInTheDocument();
-    expect(screen.queryByText('.post')).not.toBeInTheDocument();
-    expect(screen.getByText('h2')).toBeInTheDocument();
+    expect(within(itemsGroup).getByRole('button', { name: COPY.removeSelector('article') })).toHaveAttribute(
+      'aria-pressed',
+      'true'
+    );
+    expect(within(itemsGroup).queryByText(COPY.enhanceItems)).not.toBeInTheDocument();
+
+    fireEvent.click(within(itemsGroup).getByRole('button', { name: COPY.removeSelector('article') }));
+
+    expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('a[href], div, main');
+    expect(screen.getByLabelText(COPY.enhanceItems)).toBeChecked();
+    expect(within(itemsGroup).getByRole('button', { name: COPY.addSelector('article') })).toHaveAttribute(
+      'aria-pressed',
+      'false'
+    );
+    expect(within(itemsGroup).getByRole('button', { name: COPY.removeSelector('div') })).toHaveAttribute(
+      'aria-pressed',
+      'true'
+    );
+    fireEvent.input(screen.getByLabelText(COPY.itemsSelector), { target: { value: 'a[href], main' } });
+    expect(within(itemsGroup).getByRole('button', { name: COPY.addSelector('div') })).toHaveAttribute(
+      'aria-pressed',
+      'false'
+    );
+    expect(within(itemsGroup).getByRole('button', { name: COPY.removeSelector('main') })).toHaveAttribute(
+      'aria-pressed',
+      'true'
+    );
     expect(screen.getByRole('group', { name: COPY.choicesFor(COPY.fieldTitle) })).toBeInTheDocument();
   });
 
-  it('applies a field candidate without changing items', async () => {
+  it('adds a title chip without changing items or enhance', async () => {
     echoValidate();
     stubSuggest(
       rankedSuggestSuccessBody({
-        items: [{ selector: 'article', enhance: false }],
+        items: [{ selector: 'article', enhance: true }],
         title: [{ selector: 'h2' }, { selector: 'h1' }],
       })
     );
     renderStudio();
     await waitFor(() => expect(screen.getByText('h2')).toBeInTheDocument());
+    fireEvent.click(screen.getByLabelText(COPY.enhanceItems));
 
     const titleGroup = screen.getByRole('group', { name: COPY.choicesFor(COPY.fieldTitle) });
-    fireEvent.click(within(titleGroup).getAllByRole('button', { name: COPY.useSuggestion })[0]!);
+    fireEvent.click(within(titleGroup).getByRole('button', { name: COPY.addSelector('h2') }));
 
     fireEvent.click(screen.getByRole('button', { name: COPY.fieldMissing(COPY.fieldTitle) }));
     expect(screen.getByLabelText(COPY.selector)).toHaveValue('h2');
     expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('a[href]');
-    const remainingTitle = screen.getByRole('group', { name: COPY.choicesFor(COPY.fieldTitle) });
-    expect(within(remainingTitle).queryByText('h2')).not.toBeInTheDocument();
-    expect(within(remainingTitle).getByText('h1')).toBeInTheDocument();
+    expect(screen.getByLabelText(COPY.enhanceItems)).toBeChecked();
+    expect(within(titleGroup).getByRole('button', { name: COPY.removeSelector('h2') })).toHaveAttribute(
+      'aria-pressed',
+      'true'
+    );
+    expect(within(titleGroup).getByRole('button', { name: COPY.addSelector('h1') })).toHaveAttribute(
+      'aria-pressed',
+      'false'
+    );
   });
 
   it('hides empty candidate buckets', async () => {
@@ -449,13 +484,13 @@ describe('ConfigStudio', () => {
   it('reveals read-only yaml captioned as a selectors fragment', async () => {
     renderStudio();
     await waitFor(() => expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('a[href]'));
-    fireEvent.click(await waitForItemsChoiceUse());
-    await waitFor(() => expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('article'));
+    fireEvent.click(await waitForItemsChip());
+    await waitFor(() => expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('a[href], article'));
 
     fireEvent.click(screen.getByRole('button', { name: COPY.viewAsYaml }));
 
     expect(document.querySelector('textarea')).toBeNull();
-    await waitFor(() => expect(screen.getByText(/selector: article/)).toBeInTheDocument());
+    await waitFor(() => expect(screen.getByText(/selector: a\[href\], article/)).toBeInTheDocument());
     expect(screen.getByText(COPY.yamlFragmentCaption)).toBeInTheDocument();
   });
 
@@ -464,13 +499,14 @@ describe('ConfigStudio', () => {
     const save = screen.getByRole('button', { name: COPY.saveAndGenerate });
     expect(save).toBeDisabled();
     await waitFor(() => expect(save).toBeEnabled());
-    fireEvent.click(await waitForItemsChoiceUse());
-    await waitFor(() => expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('article'));
+    fireEvent.click(await waitForItemsChip());
+    await waitFor(() => expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('a[href], article'));
     await waitFor(() => expect(save).toBeEnabled());
 
     fireEvent.click(save);
 
     await waitFor(() => expect(onGenerate).toHaveBeenCalled());
-    expect(onGenerate.mock.calls[0]?.[0]).toEqual({ items: { selector: 'article', enhance: true } });
+    expect(onGenerate.mock.calls[0]?.[0]).toEqual({ items: { selector: 'a[href], article' } });
+    expect(screen.getByLabelText(COPY.enhanceItems)).not.toBeChecked();
   });
 });
diff --git a/frontend/src/__tests__/selectorDraft.test.ts b/frontend/src/__tests__/selectorDraft.test.ts
new file mode 100644
index 00000000..a59dc707
--- /dev/null
+++ b/frontend/src/__tests__/selectorDraft.test.ts
@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest';
+import {
+  joinSelectorParts,
+  selectorChoiceParts,
+  hasEverySelectorPart,
+  splitSelectorParts,
+  toggleSelectorParts,
+} from '../studio/selectorDraft';
+
+describe('selector parts', () => {
+  it('splits on commas outside parens, brackets, and quotes, and drops empty parts', () => {
+    expect(splitSelectorParts('a[href], article, div')).toEqual(['a[href]', 'article', 'div']);
+    expect(splitSelectorParts('article,,  div')).toEqual(['article', 'div']);
+    expect(splitSelectorParts('  article , div  ')).toEqual(['article', 'div']);
+    expect(splitSelectorParts('div:not(.a, .b), article')).toEqual(['div:not(.a, .b)', 'article']);
+    expect(splitSelectorParts('div:has(a[href]), article')).toEqual(['div:has(a[href])', 'article']);
+    expect(splitSelectorParts('a[href="foo, bar"], main')).toEqual(['a[href="foo, bar"]', 'main']);
+    expect(splitSelectorParts("a[href='foo, bar'], main")).toEqual(["a[href='foo, bar']", 'main']);
+    expect(splitSelectorParts('')).toEqual([]);
+  });
+
+  it('joins parts with a comma and a space', () => {
+    expect(joinSelectorParts(['a[href]', 'article', 'main'])).toBe('a[href], article, main');
+  });
+
+  it('treats a candidate as used when every part is present, not only on a whole-string match', () => {
+    expect(hasEverySelectorPart('a[href], article, div, main', 'article, div')).toBe(true);
+    expect(hasEverySelectorPart('article, div', 'article, div, main')).toBe(false);
+    expect(hasEverySelectorPart('article', 'article, div')).toBe(false);
+  });
+
+  it('adds candidate parts in order, dedupes exact parts, and removes one part without the others', () => {
+    const added = toggleSelectorParts(toggleSelectorParts('a[href]', 'article, div'), 'main');
+    expect(added).toBe('a[href], article, div, main');
+    expect(hasEverySelectorPart(added, 'article, div')).toBe(true);
+    expect(hasEverySelectorPart(added, 'main')).toBe(true);
+
+    const removed = toggleSelectorParts(added, 'article');
+    expect(removed).toBe('a[href], div, main');
+    expect(removed.includes('article')).toBe(false);
+
+    expect(toggleSelectorParts('article', 'article, div')).toBe('article, div');
+    expect(toggleSelectorParts('a[href], article, div', 'article, div')).toBe('a[href]');
+  });
+
+  it('projects one chip part per candidate part in first-seen order', () => {
+    expect(
+      selectorChoiceParts([{ selector: 'article, div' }, { selector: 'main' }, { selector: 'div, article' }])
+    ).toEqual(['article', 'div', 'main']);
+  });
+});
diff --git a/frontend/src/__tests__/useStudio.test.ts b/frontend/src/__tests__/useStudio.test.ts
index d9f9cca6..41288633 100644
--- a/frontend/src/__tests__/useStudio.test.ts
+++ b/frontend/src/__tests__/useStudio.test.ts
@@ -3,9 +3,8 @@ import { renderHook, act, waitFor } from '@testing-library/preact';
 import {
   draftFromSelectors,
   emptyDraft,
+  selectorChoiceParts,
   selectorsFromDraft,
-  unusedFieldCandidates,
-  unusedItemsCandidates,
   withFieldSelector,
 } from '../studio/selectorDraft';
 import { STUDIO_PREVIEW_SETTLE_MS, STUDIO_VALIDATE_DELAY_MS, useStudio } from '../studio/useStudio';
@@ -192,23 +191,20 @@ describe('selector draft', () => {
     ).toBeUndefined();
   });
 
-  it('hides items and field candidates that already match the draft', () => {
+  it('splits a multi-part candidate into parts the draft can add or remove independently', () => {
     const drafted = draftFromSelectors({
-      items: { selector: 'article', enhance: true },
-      title: { selector: 'h2', extractor: 'text' },
+      items: { selector: 'a[href]', enhance: true },
+      title: { selector: '', extractor: 'text' },
     });
     expect(drafted).toBeDefined();
     if (!drafted) return;
 
-    expect(
-      unusedItemsCandidates(drafted, [
-        { selector: 'article', enhance: true },
-        { selector: '.post', enhance: false },
-      ])
-    ).toEqual([{ selector: '.post', enhance: false }]);
-    expect(unusedFieldCandidates(drafted, 'title', [{ selector: 'h2' }, { selector: 'h1' }])).toEqual([
-      { selector: 'h1' },
+    expect(selectorChoiceParts([{ selector: 'article, div', enhance: true }, { selector: 'main' }])).toEqual([
+      'article',
+      'div',
+      'main',
     ]);
+    expect(drafted.enhance).toBe(true);
   });
 });
 
@@ -387,7 +383,7 @@ describe('useStudio', () => {
     expect(result.current.state.live.status).toBe('ready');
   });
 
-  it('stores ranked candidates without overwriting the draft until Use is applied', async () => {
+  it('stores ranked candidates without overwriting the draft until a chip is toggled', async () => {
     const pendingSuggestion = Promise.withResolvers<Response>();
     mockStudioFetch(fetchMock, {
       suggest: () => pendingSuggestion.promise,
@@ -446,11 +442,11 @@ describe('useStudio', () => {
     expect(callsTo(fetchMock, '/feeds/suggest_selectors')).toHaveLength(1);
 
     act(() => {
-      result.current.applyItemsCandidate({ selector: '.post', enhance: true });
+      result.current.toggleItemsSelector('.post');
     });
 
-    expect(result.current.state.draft.itemsSelector).toBe('.post');
-    expect(result.current.state.draft.enhance).toBe(true);
+    expect(result.current.state.draft.itemsSelector).toBe('a[href], .post');
+    expect(result.current.state.draft.enhance).toBe(false);
     expect(result.current.state.draft.fields.title.selector).toBe('');
   });
 
@@ -509,7 +505,7 @@ describe('useStudio', () => {
     expect(live.sample.items[1]?.imageUrl).toBeUndefined();
   });
 
-  it('applies only the clicked items candidate onto the draft', async () => {
+  it('toggles only the clicked items parts and leaves enhance unchanged', async () => {
     mockStudioFetch(fetchMock, {
       suggest: () =>
         Response.json(
@@ -537,16 +533,26 @@ describe('useStudio', () => {
     expect(result.current.state.draft.enhance).toBe(false);
 
     act(() => {
-      result.current.applyItemsCandidate({ selector: '.post', enhance: true });
+      result.current.toggleItemsSelector('.post');
     });
 
-    expect(result.current.state.draft.itemsSelector).toBe('.post');
-    expect(result.current.state.draft.enhance).toBe(true);
+    expect(result.current.state.draft.itemsSelector).toBe('article.bad, .post');
+    expect(result.current.state.draft.enhance).toBe(false);
     expect(result.current.state.draft.fields.title.selector).toBe('');
     expect(result.current.suggestion.title).toEqual([{ selector: 'h2' }]);
+
+    act(() => {
+      result.current.toggleItemsSelector('article, div');
+    });
+    act(() => {
+      result.current.toggleItemsSelector('article');
+    });
+
+    expect(result.current.state.draft.itemsSelector).toBe('article.bad, .post, div');
+    expect(result.current.state.draft.enhance).toBe(false);
   });
 
-  it('applies only the clicked field candidate', async () => {
+  it('toggles only the clicked field parts', async () => {
     mockStudioFetch(fetchMock, {
       suggest: () =>
         Response.json(
@@ -564,11 +570,13 @@ describe('useStudio', () => {
     await waitFor(() => expect(result.current.suggestion.title).toHaveLength(2));
 
     act(() => {
-      result.current.applyFieldCandidate('title', { selector: 'h2' });
+      result.current.setEnhance(true);
+      result.current.toggleFieldSelector('title', 'h2');
     });
 
     expect(result.current.state.draft.fields.title.selector).toBe('h2');
     expect(result.current.state.draft.itemsSelector).toBe('a[href]');
+    expect(result.current.state.draft.enhance).toBe(true);
   });
 
   it('fails closed when validate is unauthorized', async () => {
diff --git a/frontend/src/components/ConfigStudio.tsx b/frontend/src/components/ConfigStudio.tsx
index e079ec8a..06238b27 100644
--- a/frontend/src/components/ConfigStudio.tsx
+++ b/frontend/src/components/ConfigStudio.tsx
@@ -6,20 +6,14 @@ import { PreviewItem } from './PreviewItem';
 import { Notice } from './Notice';
 import {
   issuePlace,
+  selectorChoiceParts,
+  hasEverySelectorPart,
   STUDIO_FIELDS,
-  unusedFieldCandidates,
-  unusedItemsCandidates,
   type StudioDraft,
   type StudioFieldId,
 } from '../studio/selectorDraft';
 import { canSaveStudio, studioIssues, useStudio, type StudioState } from '../studio/useStudio';
-import type {
-  StudioFieldCandidate,
-  StudioIssue,
-  StudioItemsCandidate,
-  StudioSampleItem,
-  StudioSuggestion,
-} from '../studio/studioService';
+import type { StudioIssue, StudioSampleItem, StudioSuggestion } from '../studio/studioService';
 
 /** Settle delay before URL edits re-trigger suggest / validate / preview. */
 export const STUDIO_URL_SETTLE_MS = 400;
@@ -170,8 +164,8 @@ export function ConfigStudio(properties: ConfigStudioProperties) {
       <CandidateChoices
         draft={state.draft}
         suggestion={suggestion}
-        onUseItems={studio.applyItemsCandidate}
-        onUseField={studio.applyFieldCandidate}
+        onToggleItems={studio.toggleItemsSelector}
+        onToggleField={studio.toggleFieldSelector}
       />
 
       <div class="refine-enhance">
@@ -312,98 +306,91 @@ export function ConfigStudio(properties: ConfigStudioProperties) {
 function CandidateChoices({
   draft,
   suggestion,
-  onUseItems,
-  onUseField,
+  onToggleItems,
+  onToggleField,
 }: {
   readonly draft: StudioDraft;
   readonly suggestion: StudioSuggestion;
-  readonly onUseItems: (candidate: StudioItemsCandidate) => void;
-  readonly onUseField: (field: StudioFieldId, candidate: StudioFieldCandidate) => void;
+  readonly onToggleItems: (selector: string) => void;
+  readonly onToggleField: (field: StudioFieldId, selector: string) => void;
 }) {
-  const items = unusedItemsCandidates(draft, suggestion.items);
-  const title = unusedFieldCandidates(draft, 'title', suggestion.title);
-  const link = unusedFieldCandidates(draft, 'link', suggestion.link);
-  const published = unusedFieldCandidates(draft, 'published', suggestion.published);
+  const items = selectorChoiceParts(suggestion.items);
+  const title = selectorChoiceParts(suggestion.title);
+  const link = selectorChoiceParts(suggestion.link);
+  const published = selectorChoiceParts(suggestion.published);
   if (items.length === 0 && title.length === 0 && link.length === 0 && published.length === 0) {
     return;
   }
 
   return (
     <div class="refine-candidates" role="group" aria-label={COPY.selectorChoices}>
-      <CandidateBucket
+      <SelectorChips
         heading={COPY.itemsSelector}
         label={COPY.choicesFor(COPY.itemsSelector)}
-        choices={items.map((candidate) => ({
-          key: `items:${candidate.selector}:${candidate.enhance ? '1' : '0'}`,
-          selector: candidate.selector,
-          enhance: candidate.enhance,
-          onUse: () => onUseItems(candidate),
-        }))}
+        current={draft.itemsSelector}
+        parts={items}
+        onToggle={onToggleItems}
       />
-      <CandidateBucket
+      <SelectorChips
         heading={COPY.fieldTitle}
         label={COPY.choicesFor(COPY.fieldTitle)}
-        choices={title.map((candidate) => ({
-          key: `title:${candidate.selector}`,
-          selector: candidate.selector,
-          onUse: () => onUseField('title', candidate),
-        }))}
+        current={draft.fields.title.selector}
+        parts={title}
+        onToggle={(selector) => onToggleField('title', selector)}
       />
-      <CandidateBucket
+      <SelectorChips
         heading={COPY.fieldLink}
         label={COPY.choicesFor(COPY.fieldLink)}
-        choices={link.map((candidate) => ({
-          key: `link:${candidate.selector}`,
-          selector: candidate.selector,
-          onUse: () => onUseField('link', candidate),
-        }))}
+        current={draft.fields.link.selector}
+        parts={link}
+        onToggle={(selector) => onToggleField('link', selector)}
       />
-      <CandidateBucket
+      <SelectorChips
         heading={COPY.fieldPublished}
         label={COPY.choicesFor(COPY.fieldPublished)}
-        choices={published.map((candidate) => ({
-          key: `published:${candidate.selector}`,
-          selector: candidate.selector,
-          onUse: () => onUseField('published', candidate),
-        }))}
+        current={draft.fields.published.selector}
+        parts={published}
+        onToggle={(selector) => onToggleField('published', selector)}
       />
     </div>
   );
 }
 
-function CandidateBucket({
+function SelectorChips({
   heading,
   label,
-  choices,
+  current,
+  parts,
+  onToggle,
 }: {
   readonly heading: string;
   readonly label: string;
-  readonly choices: readonly {
-    readonly key: string;
-    readonly selector: string;
-    readonly enhance?: boolean;
-    readonly onUse: () => void;
-  }[];
+  readonly current: string;
+  readonly parts: readonly string[];
+  readonly onToggle: (selector: string) => void;
 }) {
-  if (choices.length === 0) return;
+  if (parts.length === 0) return;
 
   return (
     <div class="refine-candidates__bucket" role="group" aria-label={label}>
       <p class="ui-eyebrow">{heading}</p>
-      <ul class="refine-candidates__list">
-        {choices.map((choice) => (
-          <li key={choice.key} class="refine-suggestion">
-            <p class="refine-suggestion__text">
-              <code class="input--mono refine-suggestion__selector">{choice.selector}</code>
-              {choice.enhance ? (
-                <span class="field-help refine-suggestion__enhance">{COPY.enhanceItems}</span>
-              ) : undefined}
-            </p>
-            <button type="button" class="btn btn--quiet" onClick={choice.onUse}>
-              {COPY.useSuggestion}
-            </button>
-          </li>
-        ))}
+      <ul class="refine-candidates__chips">
+        {parts.map((selector) => {
+          const pressed = hasEverySelectorPart(current, selector);
+          return (
+            <li key={selector}>
+              <button
+                type="button"
+                class={pressed ? 'refine-chip is-pressed' : 'refine-chip'}
+                aria-pressed={pressed}
+                aria-label={pressed ? COPY.removeSelector(selector) : COPY.addSelector(selector)}
+                onClick={() => onToggle(selector)}
+              >
+                {selector}
+              </button>
+            </li>
+          );
+        })}
       </ul>
     </div>
   );
diff --git a/frontend/src/journey/copy.ts b/frontend/src/journey/copy.ts
index 6f27a2a5..d57996b3 100644
--- a/frontend/src/journey/copy.ts
+++ b/frontend/src/journey/copy.ts
@@ -73,7 +73,8 @@ export const COPY = {
   /** Ranked refine choices; buckets may be empty. */
   selectorChoices: 'Selector choices',
   choicesFor: (name: string) => `${name} options`,
-  useSuggestion: 'Use',
+  addSelector: (selector: string) => `Add ${selector}`,
+  removeSelector: (selector: string) => `Remove ${selector}`,
   saveAndGenerate: 'Save and generate feed',
   viewAsYaml: 'View as YAML',
   yamlFragmentCaption: 'Selectors fragment — not a feeds.yml config',
diff --git a/frontend/src/studio/selectorDraft.ts b/frontend/src/studio/selectorDraft.ts
index efe5f2d6..34a91d0c 100644
--- a/frontend/src/studio/selectorDraft.ts
+++ b/frontend/src/studio/selectorDraft.ts
@@ -92,44 +92,98 @@ export function withFieldSelector(draft: StudioDraft, field: StudioFieldId, sele
   return mapField(draft, field, () => ({ selector }));
 }
 
-export function applyItemsSuggestion(
-  draft: StudioDraft,
-  itemsSelector: string,
-  isEnhanced: boolean
-): StudioDraft {
-  return { ...draft, itemsSelector, enhance: isEnhanced };
+/**
+ * Selector parts split on commas outside `()`, `[]`, and quotes.
+ * Empty parts are dropped. Join uses `", "` so toggles share one authored string.
+ */
+export function splitSelectorParts(selector: string): readonly string[] {
+  const parts: string[] = [];
+  let start = 0;
+  let quote: '"' | "'" | undefined;
+  let paren = 0;
+  let bracket = 0;
+
+  for (let index = 0; index < selector.length; index += 1) {
+    const char = selector[index];
+    if (char === '\\') {
+      index += 1;
+      continue;
+    }
+    if (quote) {
+      if (char === quote) quote = undefined;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      continue;
+    }
+    if (char === '(') {
+      paren += 1;
+      continue;
+    }
+    if (char === ')' && paren > 0) {
+      paren -= 1;
+      continue;
+    }
+    if (char === '[') {
+      bracket += 1;
+      continue;
+    }
+    if (char === ']' && bracket > 0) {
+      bracket -= 1;
+      continue;
+    }
+    if (char === ',' && paren === 0 && bracket === 0) {
+      pushSelectorPart(parts, selector.slice(start, index));
+      start = index + 1;
+    }
+  }
+
+  pushSelectorPart(parts, selector.slice(start));
+  return parts;
 }
 
-/** True when the authored draft already matches this items candidate (hide that Use row). */
-export function isDraftMatchingItemsCandidate(
-  draft: StudioDraft,
-  candidate: { readonly selector: string; readonly enhance: boolean }
-): boolean {
-  return draft.itemsSelector === candidate.selector && draft.enhance === candidate.enhance;
+export function joinSelectorParts(parts: readonly string[]): string {
+  return parts.join(', ');
 }
 
-/** True when the authored field selector already matches this candidate (hide that Use row). */
-export function isDraftMatchingFieldCandidate(
-  draft: StudioDraft,
-  field: StudioFieldId,
-  candidate: { readonly selector: string }
-): boolean {
-  return draft.fields[field].selector === candidate.selector;
+/** True when every part of `candidate` is already an exact part of `current`. */
+export function hasEverySelectorPart(current: string, candidate: string): boolean {
+  const wanted = splitSelectorParts(candidate);
+  if (wanted.length === 0) return false;
+  const present = splitSelectorParts(current);
+  return wanted.every((part) => present.includes(part));
 }
 
-export function unusedItemsCandidates<T extends { readonly selector: string; readonly enhance: boolean }>(
-  draft: StudioDraft,
-  candidates: readonly T[]
-): readonly T[] {
-  return candidates.filter((candidate) => !isDraftMatchingItemsCandidate(draft, candidate));
+/**
+ * Add missing candidate parts in order, or remove those parts when all are present.
+ * Existing parts stay in their current order. New parts append and exact duplicates are skipped.
+ */
+export function toggleSelectorParts(current: string, candidate: string): string {
+  const present = splitSelectorParts(current);
+  const incoming = splitSelectorParts(candidate);
+  if (incoming.length === 0) return joinSelectorParts(present);
+  if (incoming.every((part) => present.includes(part))) {
+    const remove = new Set(incoming);
+    return joinSelectorParts(present.filter((part) => !remove.has(part)));
+  }
+
+  const next = [...present];
+  for (const part of incoming) {
+    if (!next.includes(part)) next.push(part);
+  }
+  return joinSelectorParts(next);
 }
 
-export function unusedFieldCandidates<T extends { readonly selector: string }>(
-  draft: StudioDraft,
-  field: StudioFieldId,
-  candidates: readonly T[]
-): readonly T[] {
-  return candidates.filter((candidate) => !isDraftMatchingFieldCandidate(draft, field, candidate));
+/** One chip per selector part, in first-seen candidate order. */
+export function selectorChoiceParts(candidates: readonly { readonly selector: string }[]): readonly string[] {
+  const parts: string[] = [];
+  for (const candidate of candidates) {
+    for (const part of splitSelectorParts(candidate.selector)) {
+      if (!parts.includes(part)) parts.push(part);
+    }
+  }
+  return parts;
 }
 
 export function issuePlace(path: readonly string[]): IssuePlace {
@@ -144,6 +198,11 @@ export function issuePlace(path: readonly string[]): IssuePlace {
   return { kind: 'field', field, control: 'selector' };
 }
 
+function pushSelectorPart(parts: string[], raw: string) {
+  const trimmed = raw.trim();
+  if (trimmed.length > 0) parts.push(trimmed);
+}
+
 function emptyFields(): Record<StudioFieldId, FieldDraft> {
   return {
     title: blankField(),
diff --git a/frontend/src/studio/useStudio.ts b/frontend/src/studio/useStudio.ts
index a908fcec..9291bf52 100644
--- a/frontend/src/studio/useStudio.ts
+++ b/frontend/src/studio/useStudio.ts
@@ -7,18 +7,16 @@ import {
   StudioRequestError,
   suggestStudioSelectors,
   validateStudioSelectors,
-  type StudioFieldCandidate,
   type StudioIssue,
-  type StudioItemsCandidate,
   type StudioPreview,
   type StudioSuggestion,
   type StudioValidationOutcome,
 } from './studioService';
 import type { RefinedSelectorsDocument } from '../api/generated/types.gen';
 import {
-  applyItemsSuggestion,
   emptyDraft,
   selectorsFromDraft,
+  toggleSelectorParts,
   withEnhance,
   withFieldSelector,
   withItemsSelector,
@@ -257,16 +255,17 @@ export function useStudio({
     }
   }
 
-  /** Apply only the clicked items candidate — never auto-applied on suggest. */
-  function applyItemsCandidate(candidate: StudioItemsCandidate) {
+  /** Toggle parts on the items string. Suggest never writes the draft; chips never write enhance. */
+  function toggleItemsSelector(selector: string) {
     itemsTouchedReference.current = true;
-    enhanceTouchedReference.current = true;
-    editSelectors((draft) => applyItemsSuggestion(draft, candidate.selector, candidate.enhance));
+    editSelectors((draft) => withItemsSelector(draft, toggleSelectorParts(draft.itemsSelector, selector)));
   }
 
-  /** Apply only the clicked field candidate — extractors stay fixed by the draft mapper. */
-  function applyFieldCandidate(field: StudioFieldId, candidate: StudioFieldCandidate) {
-    editSelectors((draft) => withFieldSelector(draft, field, candidate.selector));
+  /** Toggle parts on one field string. Extractors stay fixed by the draft mapper. */
+  function toggleFieldSelector(field: StudioFieldId, selector: string) {
+    editSelectors((draft) =>
+      withFieldSelector(draft, field, toggleSelectorParts(draft.fields[field].selector, selector))
+    );
   }
 
   function retryPreview() {
@@ -302,8 +301,8 @@ export function useStudio({
     setItemsSelector,
     setEnhance,
     setFieldSelector,
-    applyItemsCandidate,
-    applyFieldCandidate,
+    toggleItemsSelector,
+    toggleFieldSelector,
     requestSuggestion: () => {
       void requestSuggestion();
     },
diff --git a/frontend/src/styles/main.css b/frontend/src/styles/main.css
index 2e611294..8a247923 100644
--- a/frontend/src/styles/main.css
+++ b/frontend/src/styles/main.css
@@ -593,33 +593,37 @@
   gap: var(--space-2);
 }
 
-.refine-candidates__list {
+.refine-candidates__chips {
   display: flex;
-  flex-direction: column;
+  flex-wrap: wrap;
   gap: var(--space-2);
   margin: 0;
   padding: 0;
   list-style: none;
 }
 
-.refine-suggestion {
-  display: flex;
-  flex-wrap: wrap;
-  align-items: center;
-  gap: var(--space-3);
-}
-
-.refine-suggestion__text {
+.refine-chip {
   margin: 0;
-  min-width: 0;
+  padding: var(--space-1) var(--space-2);
+  border: var(--border-width) solid var(--border-subtle);
+  border-radius: var(--radius-md);
+  background: transparent;
+  color: var(--text-body);
+  font-family: var(--font-family-mono);
+  font-size: var(--font-size-0);
+  line-height: var(--line-height-base);
+  cursor: pointer;
 }
 
-.refine-suggestion__selector {
-  word-break: break-all;
+.refine-chip:focus-visible {
+  outline: none;
+  box-shadow: var(--focus-ring);
 }
 
-.refine-suggestion__enhance {
-  margin-left: var(--space-2);
+.refine-chip.is-pressed {
+  border-color: var(--border-strong);
+  background: var(--surface-elevated);
+  color: var(--text-strong);
 }
 
 .refine-enhance {

From 8209131e58050e48342979fa3c86da7773b6f4b0 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Mon, 21 Sep 2026 15:09:05 +0200
Subject: [PATCH 070/108] fix(refine): keep the meadow visible and render
 selector pills

Selector edits were clearing the live preview to idle, which flashed the create-time meadow. Keep the last sample and mark it loading until the next preview returns. Render selector choices as pills with the existing radius, spacing, and surface tokens.
---
 docs/design-system.md                        | 26 ++++-----
 frontend/src/__tests__/ConfigStudio.test.tsx | 46 +++++++++++++++
 frontend/src/__tests__/useStudio.test.ts     | 50 ++++++++++++++++
 frontend/src/components/ConfigStudio.tsx     | 61 +++++++++++++-------
 frontend/src/journey/copy.ts                 |  2 +-
 frontend/src/studio/useStudio.ts             | 44 ++++++++++++--
 frontend/src/styles/main.css                 | 14 ++++-
 7 files changed, 198 insertions(+), 45 deletions(-)

diff --git a/docs/design-system.md b/docs/design-system.md
index c16b53e6..2db24d5f 100644
--- a/docs/design-system.md
+++ b/docs/design-system.md
@@ -40,26 +40,26 @@ If a page looks like it came from a different product, the change is wrong even
 
 - **Create:** URL field is the task. Visiting `#/create` or `#!/create` remounts create; hashbang aliases canonicalize to `#/create`. Bare create does not auto-submit. When the typed query finds catalog entries (URL equivalence or text substring), show matching feeds as a subordinate list under the field — never a second primary task or in-app catalog browser. On an empty Create URL, up to three Feed Directory starters may appear as subordinate chrome (lean: `.ui-eyebrow` + list + demoted `utility-link` escape under the list when creation is enabled; Notice when creation is disabled). Escape and utility-strip share **Browse Feed Directory (N)** (`catalogEntries.length`); hide starters and the under-list escape while typing, when find has hits, or while creating.
 - **Token gate:** a native `<dialog>` over the still-mounted, inert URL task (one interactive task). Auth copy is in-field (`tokenError`); ActionFeedback stays on create. Access Token persists until Logout with no storage UI.
-- **Result:** primary CTA is **Copy feed URL**, and it takes initial focus. Open feed / JSON / feed-reader are demoted secondary actions and stay available while preview loads. Preview is one meadow and non-blocking confirmation only. Guest results stay compact: at most 5 items, no images, no selector controls. An authenticated, studio-enabled result keeps that same frame: a demoted **Refine selectors** action in `ui-actions` (collapsed by default). Opening it mounts selector controls **above** the meadow; closing it returns to the static meadow without discarding the in-memory draft. Studio validate/preview/suggest do not run until the panel opens. Selector edits replace the meadow with live studio output; they do not add a second list. **Save and generate feed** is the only primary action inside those controls. Member previews may show up to 10 items and safe HTTP(S) images.
+- **Result:** primary CTA is **Copy feed URL**, and it takes initial focus. Open feed / JSON / feed-reader are demoted secondary actions and stay available while preview loads. Preview is one meadow and non-blocking confirmation only. Guest results stay compact: at most 5 items, no images, no selector controls. An authenticated, studio-enabled result keeps that same frame: a demoted **Refine selectors** action in `ui-actions` (collapsed by default). Opening it mounts selector controls **above** the meadow; closing it returns to the static meadow without discarding the in-memory draft. Studio validate/preview/suggest do not run until the panel opens. Selector edits keep the previous meadow visible and mark it loading until live studio output replaces it. They do not add a second list, and they do not return to the create-time meadow once a studio sample exists. Until that sample exists, including while the first studio preview loads, the result keeps its create-time meadow. The studio meadow is captioned as the page already fetched for this URL. **Save and generate feed** is the only primary action inside those controls. Member previews may show up to 10 items and safe HTTP(S) images.
 - **Empty extraction:** **Refine selectors** is one quiet action beside Try again when the extraction is empty, studio is enabled, and an access token is present. It is not offered for other create errors, guests, or a studio-off instance.
-- **Refine:** `#/refine` is memory-bound extraction-empty recovery for an authenticated studio (see [personas.md](personas.md) J2). No token in the route. A successful in-memory result replaces `#/refine` with `#/result/:token`; refinement of that feed stays on the result behind the same demoted **Refine selectors** gate. Standalone recovery uses the same frame as an expanded Result: a `result-shell` / `layout-stack` rail — never a mega-card bisected by the fixed footer, never a two-column paddock. First viewport leads with compact controls (items selector, ranked **Selector choices** per bucket as wrapping add/remove chips, a large Enhance hit target, and **Save and generate feed** as the only `btn--primary` in `ui-actions`), then the live preview meadow (`.ui-item-list`) after validation. URL, native-feed Notice, and View as YAML are demoted support below the meadow. Changing the URL re-suggests and re-previews without leaving the current surface or running catalog find; empty URL recovers onto remounted `#/create`. Ranked candidates (items, title, link, published) are wrapping chips on the authored selector. A chip adds or removes its selector parts in the comma-joined draft string; suggest does not write that string. Chips do not change Enhance. Empty buckets stay hidden. Wire is the typed closed selectors document (no strip/trim/affix cleanup UI). Fix a field opens one selector panel **in the stack** for Title, Link, or Published date. View as YAML is read-only and captioned as a selectors fragment — not a feeds.yml. Save-failure Notices use wire `Decision#message` — never create-journey copy. When studio is disabled or the caller has no token, Refine actions stay hidden and `#/refine` bounces to create. Focus on standalone recovery is the items selector; a successful Result keeps focus on Copy whether Refine is open or closed.
+- **Refine:** `#/refine` is memory-bound extraction-empty recovery for an authenticated studio (see [personas.md](personas.md) J2). No token in the route. A successful in-memory result replaces `#/refine` with `#/result/:token`; refinement of that feed stays on the result behind the same demoted **Refine selectors** gate. Standalone recovery uses the same frame as an expanded Result: a `result-shell` / `layout-stack` rail — never a mega-card bisected by the fixed footer, never a two-column paddock. First viewport leads with compact controls (items selector, ranked **Selector choices** per bucket as wrapping add/remove pills, a large Enhance hit target, and **Save and generate feed** as the only `btn--primary` in `ui-actions`), then the live preview meadow (`.ui-item-list`) after validation. URL, native-feed Notice, and View as YAML are demoted support below the meadow. Changing the URL re-suggests and re-previews without leaving the current surface or running catalog find; empty URL recovers onto remounted `#/create`. Ranked candidates (items, title, link, published) are wrapping pills on the authored selector: `--radius-pill`, `--space-2`/`--space-3` padding, a transparent outline when idle, and `--surface-elevated` with `--border-strong` when pressed. A pill and its list item use `min-width: 0` and `max-width: 100%`; the pill uses `overflow-wrap: anywhere`. A pill adds or removes its selector parts in the comma-joined draft string; suggest does not write that string. Pills do not change Enhance. Empty buckets stay hidden. Wire is the typed closed selectors document (no strip/trim/affix cleanup UI). Fix a field opens one selector panel **in the stack** for Title, Link, or Published date. View as YAML is read-only and captioned as a selectors fragment — not a feeds.yml. Save-failure Notices use wire `Decision#message` — never create-journey copy. When studio is disabled or the caller has no token, Refine actions stay hidden and `#/refine` bounces to create. Focus on standalone recovery is the items selector; a successful Result keeps focus on Copy whether Refine is open or closed.
 - **Unmatched result:** `#/result/:token` is valid only with a matching in-memory result. Missing or mismatched tokens recover onto remounted `#/create` (no API rehydrate, no failure chrome, no durable shareable result page).
 - **Status eyebrow:** one vocabulary (`Feed ready`) on the result header; preview progress lives in the preview section.
 - **Focus:** create autofocuses the URL field; token autofocuses the token field; result focuses the Copy control; standalone extraction-empty refine focuses the items selector.
 
 ### Vocabulary
 
-| Job | Words |
-| --- | --- |
-| Input | **URL** |
-| Output | **Feed URL** |
-| Create | **Create feed** / **Creating feed** |
-| Result | **Feed ready** / **Copy feed URL** |
-| Refine | **Refine selectors** / **Selector choices** / **Add** / **Remove** / **Save and generate feed** / **View as YAML** |
-| Retry | **Try again** (button only) |
-| Preview | **Checking preview** / **Check again** |
-| Catalog | **Feed Directory** |
-| Token | **Access token** |
+| Job     | Words                                                                                                              |
+| ------- | ------------------------------------------------------------------------------------------------------------------ |
+| Input   | **URL**                                                                                                            |
+| Output  | **Feed URL**                                                                                                       |
+| Create  | **Create feed** / **Creating feed**                                                                                |
+| Result  | **Feed ready** / **Copy feed URL**                                                                                 |
+| Refine  | **Refine selectors** / **Selector choices** / **Add** / **Remove** / **Save and generate feed** / **View as YAML** |
+| Retry   | **Try again** (button only)                                                                                        |
+| Preview | **Checking preview** / **Check again** / **Based on the page already fetched for this URL**                        |
+| Catalog | **Feed Directory**                                                                                                 |
+| Token   | **Access token**                                                                                                   |
 
 ## Non-Negotiable Surface Rules
 
diff --git a/frontend/src/__tests__/ConfigStudio.test.tsx b/frontend/src/__tests__/ConfigStudio.test.tsx
index 1e177304..6d58dbc4 100644
--- a/frontend/src/__tests__/ConfigStudio.test.tsx
+++ b/frontend/src/__tests__/ConfigStudio.test.tsx
@@ -472,6 +472,52 @@ describe('ConfigStudio', () => {
     expect(document.querySelector('img')).toBeNull();
   });
 
+  it('keeps the visible meadow while the next preview has not returned', async () => {
+    echoValidate();
+    const firstPreview = Promise.withResolvers<Response>();
+    let previewCalls = 0;
+    server.use(
+      http.post('/api/v1/feeds/preview', () => {
+        previewCalls += 1;
+        if (previewCalls === 1) return firstPreview.promise;
+        return HttpResponse.json(previewWithImage());
+      })
+    );
+
+    render(
+      <ConfigStudio
+        placement="inline"
+        fallback={<p>Create-time meadow</p>}
+        url={pageUrl}
+        token="tok"
+        onUrlChange={vi.fn()}
+        onUrlCleared={vi.fn()}
+        onGenerate={vi.fn(async () => {})}
+      />
+    );
+
+    expect(screen.getByText('Create-time meadow')).toBeInTheDocument();
+    fireEvent.click(await waitForItemsChip());
+
+    await waitFor(() => expect(screen.getByText(COPY.previewChecking)).toBeInTheDocument());
+    expect(screen.getByText('Create-time meadow')).toBeInTheDocument();
+    expect(screen.queryByText('With image')).not.toBeInTheDocument();
+
+    firstPreview.resolve(HttpResponse.json(previewWithImage()));
+    await waitFor(() => expect(screen.getByText('With image')).toBeInTheDocument());
+    expect(screen.queryByText('Create-time meadow')).not.toBeInTheDocument();
+    expect(screen.queryByText(COPY.previewChecking)).not.toBeInTheDocument();
+
+    const nextPreview = Promise.withResolvers<Response>();
+    server.use(http.post('/api/v1/feeds/preview', () => nextPreview.promise));
+    fireEvent.click(itemsChip(COPY.removeSelector('article')));
+
+    await waitFor(() => expect(screen.getByText(COPY.previewChecking)).toBeInTheDocument());
+    expect(screen.getByText('With image')).toBeInTheDocument();
+    expect(screen.queryByText('Create-time meadow')).not.toBeInTheDocument();
+    expect(document.querySelectorAll('.ui-item-list')).toHaveLength(1);
+  });
+
   it('offers check again when the live preview cannot be fetched', async () => {
     echoValidate();
     server.use(http.post('/api/v1/feeds/preview', () => HttpResponse.error()));
diff --git a/frontend/src/__tests__/useStudio.test.ts b/frontend/src/__tests__/useStudio.test.ts
index 41288633..a37063f8 100644
--- a/frontend/src/__tests__/useStudio.test.ts
+++ b/frontend/src/__tests__/useStudio.test.ts
@@ -358,6 +358,56 @@ describe('useStudio', () => {
     expect(callsTo(fetchMock, '/feeds/preview')).toHaveLength(1);
   });
 
+  it('keeps the previous sample while the next preview has not returned', async () => {
+    const firstItem = {
+      title: 'Held meadow',
+      url: 'https://example.com/held',
+      published_at: '2024-01-02',
+    };
+    let previewCount = 0;
+    const pendingPreview = Promise.withResolvers<Response>();
+    mockStudioFetch(fetchMock, {
+      preview: () => {
+        previewCount += 1;
+        if (previewCount === 1) return Response.json(previewBody([firstItem]));
+        return pendingPreview.promise;
+      },
+    });
+
+    const { result } = renderHook(() =>
+      useStudio({ url: pageUrl, token, validateDelayMs: 0, previewSettleMs: 0 })
+    );
+
+    await waitFor(() => expect(result.current.state.live.status).toBe('ready'));
+    const ready = result.current.state.live;
+    if (ready.status !== 'ready') return;
+    const previous = ready.sample;
+    expect(previous.items[0]?.title).toBe('Held meadow');
+
+    act(() => {
+      result.current.setItemsSelector('article.edited');
+    });
+
+    const refreshing = result.current.state.live;
+    expect(refreshing.status).toBe('loading');
+    if (refreshing.status !== 'loading') return;
+    expect(refreshing.held).toEqual(previous);
+
+    await waitFor(() => expect(callsTo(fetchMock, '/feeds/preview')).toHaveLength(2));
+    const inFlight = result.current.state.live;
+    expect(inFlight.status).toBe('loading');
+    if (inFlight.status !== 'loading') return;
+    expect(inFlight.held).toEqual(previous);
+
+    pendingPreview.resolve(
+      Response.json(previewBody([{ title: 'Next meadow', url: 'https://example.com/next' }]))
+    );
+    await waitFor(() => expect(result.current.state.live.status).toBe('ready'));
+    const next = result.current.state.live;
+    if (next.status !== 'ready') return;
+    expect(next.sample.items[0]?.title).toBe('Next meadow');
+  });
+
   it('suggests on mount without preview when live work waits for an edit', async () => {
     mockStudioFetch(fetchMock);
 
diff --git a/frontend/src/components/ConfigStudio.tsx b/frontend/src/components/ConfigStudio.tsx
index 06238b27..5caaced1 100644
--- a/frontend/src/components/ConfigStudio.tsx
+++ b/frontend/src/components/ConfigStudio.tsx
@@ -12,7 +12,13 @@ import {
   type StudioDraft,
   type StudioFieldId,
 } from '../studio/selectorDraft';
-import { canSaveStudio, studioIssues, useStudio, type StudioState } from '../studio/useStudio';
+import {
+  canSaveStudio,
+  studioIssues,
+  studioPreviewSample,
+  useStudio,
+  type StudioState,
+} from '../studio/useStudio';
 import type { StudioIssue, StudioSampleItem, StudioSuggestion } from '../studio/studioService';
 
 /** Settle delay before URL edits re-trigger suggest / validate / preview. */
@@ -58,8 +64,8 @@ export function ConfigStudio(properties: ConfigStudioProperties) {
   const openField = panel?.field;
   const hiddenIssues = issues.filter((issue) => isHiddenIssue(issue, openField));
   const unmappedIssues = hiddenIssues.filter((issue) => issuePlace(issue.path).kind === 'hidden');
-  const ready = state.live.status === 'ready' ? state.live.sample : undefined;
-  const nativeFeedUrl = ready?.nativeFeedUrl;
+  const sample = studioPreviewSample(state.live);
+  const nativeFeedUrl = sample?.nativeFeedUrl;
   const isBusy = state.phase === 'validating' || state.phase === 'saving' || state.live.status === 'loading';
 
   useEffect(() => {
@@ -124,18 +130,25 @@ export function ConfigStudio(properties: ConfigStudioProperties) {
     return true;
   };
 
-  const meadow =
-    isInline && state.live.status === 'idle' ? (
-      properties.fallback
-    ) : (
-      <PreviewPane
-        state={state}
-        token={token}
-        openField={openField}
-        onOpenField={openFieldPanel}
-        onRetry={studio.retryPreview}
-      />
-    );
+  const shouldShowCreateMeadow = isInline && sample === undefined && state.live.status !== 'failed';
+  const meadow = shouldShowCreateMeadow ? (
+    <>
+      {properties.fallback}
+      {state.live.status === 'loading' ? (
+        <div class="layout-rail-reading">
+          <PreviewLoading />
+        </div>
+      ) : undefined}
+    </>
+  ) : (
+    <PreviewPane
+      state={state}
+      token={token}
+      openField={openField}
+      onOpenField={openFieldPanel}
+      onRetry={studio.retryPreview}
+    />
+  );
 
   const authoring = (
     <div class="layout-rail-reading layout-stack refine-controls">
@@ -409,7 +422,7 @@ function PreviewPane({
   readonly onOpenField: (field: StudioFieldId) => void;
   readonly onRetry: () => void;
 }) {
-  const items = state.live.status === 'ready' ? state.live.sample.items : [];
+  const items = studioPreviewSample(state.live)?.items ?? [];
   const canShowImages = token.trim().length > 0;
 
   return (
@@ -434,12 +447,7 @@ function PreviewPane({
         })}
       </div>
 
-      {state.live.status === 'loading' ? (
-        <div class="preview-feedback preview-feedback--loading">
-          <span class="preview-feedback__spinner" aria-hidden="true" />
-          <span>{COPY.previewChecking}</span>
-        </div>
-      ) : undefined}
+      {state.live.status === 'loading' ? <PreviewLoading /> : undefined}
 
       {state.live.status === 'failed' ? (
         <div class="preview-feedback preview-feedback--error">
@@ -472,6 +480,15 @@ function PreviewPane({
   );
 }
 
+function PreviewLoading() {
+  return (
+    <div class="preview-feedback preview-feedback--loading">
+      <span class="preview-feedback__spinner" aria-hidden="true" />
+      <span>{COPY.previewChecking}</span>
+    </div>
+  );
+}
+
 function FieldFixPanel({
   field,
   selector,
diff --git a/frontend/src/journey/copy.ts b/frontend/src/journey/copy.ts
index d57996b3..fe3cba21 100644
--- a/frontend/src/journey/copy.ts
+++ b/frontend/src/journey/copy.ts
@@ -78,7 +78,7 @@ export const COPY = {
   saveAndGenerate: 'Save and generate feed',
   viewAsYaml: 'View as YAML',
   yamlFragmentCaption: 'Selectors fragment — not a feeds.yml config',
-  previewFetchedCaption: 'Based on the page as fetched just now',
+  previewFetchedCaption: 'Based on the page already fetched for this URL',
   nativeFeedTitle: 'This site already publishes a feed.',
   fieldTitle: 'Title',
   fieldLink: 'Link',
diff --git a/frontend/src/studio/useStudio.ts b/frontend/src/studio/useStudio.ts
index 9291bf52..4338471c 100644
--- a/frontend/src/studio/useStudio.ts
+++ b/frontend/src/studio/useStudio.ts
@@ -35,7 +35,7 @@ interface StudioDocument {
 
 export type LivePreview =
   | { readonly status: 'idle' }
-  | { readonly status: 'loading' }
+  | { readonly status: 'loading'; readonly held: StudioPreview | undefined }
   | { readonly status: 'ready'; readonly sample: StudioPreview }
   | { readonly status: 'failed'; readonly message: string };
 
@@ -147,7 +147,7 @@ export function useStudio({
         phase: 'failed',
         draft: previous.draft,
         yaml: previous.yaml,
-        live: { status: 'idle' },
+        live: restoreHeld(previous.live),
         message: error instanceof StudioRequestError ? error.message : COPY.unableToReachServer,
       }));
     }
@@ -158,11 +158,23 @@ export function useStudio({
     const yaml = outcome.yaml ?? stateReference.current.yaml;
 
     if (!outcome.valid) {
-      setState({ phase: 'invalid', draft, yaml, issues: outcome.issues, live: { status: 'idle' } });
+      setState((previous) => ({
+        phase: 'invalid',
+        draft,
+        yaml,
+        issues: outcome.issues,
+        live: restoreHeld(previous.live),
+      }));
       return;
     }
 
-    setState({ phase: 'editing', draft, yaml, validated: true, live: { status: 'idle' } });
+    setState((previous) => ({
+      phase: 'editing',
+      draft,
+      yaml,
+      validated: true,
+      live: previous.live,
+    }));
     if (live === 'after-edit' && revision === 0 && url === initialUrlReference.current) return;
     schedulePreview();
   }
@@ -174,7 +186,7 @@ export function useStudio({
       draft: update(previous.draft),
       yaml: previous.yaml,
       validated: false,
-      live: { status: 'idle' },
+      live: refreshLive(previous.live),
     }));
     setDocumentRevision((revision) => revision + 1);
   }
@@ -204,7 +216,10 @@ export function useStudio({
     setState((previous) => {
       if (!(previous.phase === 'editing' && previous.validated)) return previous;
       if (previewRequestReference.current !== requestId) return previous;
-      return assignLive(previous, { status: 'loading' });
+      return assignLive(previous, {
+        status: 'loading',
+        held: studioPreviewSample(previous.live),
+      });
     });
 
     try {
@@ -319,6 +334,23 @@ export function canSaveStudio(state: StudioState): boolean {
   return state.phase === 'editing' && state.validated;
 }
 
+/** Last studio meadow still safe to render. Absent while idle or failed. */
+export function studioPreviewSample(live: LivePreview): StudioPreview | undefined {
+  if (live.status === 'ready') return live.sample;
+  if (live.status === 'loading') return live.held;
+  return undefined;
+}
+
+function refreshLive(live: LivePreview): LivePreview {
+  return { status: 'loading', held: studioPreviewSample(live) };
+}
+
+function restoreHeld(live: LivePreview): LivePreview {
+  const held = studioPreviewSample(live);
+  if (held === undefined) return { status: 'idle' };
+  return { status: 'ready', sample: held };
+}
+
 function adoptServerDraft(sent: StudioDraft, incoming: StudioDraft): StudioDraft {
   return {
     ...sent,
diff --git a/frontend/src/styles/main.css b/frontend/src/styles/main.css
index 8a247923..054d2315 100644
--- a/frontend/src/styles/main.css
+++ b/frontend/src/styles/main.css
@@ -602,16 +602,24 @@
   list-style: none;
 }
 
+.refine-candidates__chips > li {
+  min-width: 0;
+  max-width: 100%;
+}
+
 .refine-chip {
   margin: 0;
-  padding: var(--space-1) var(--space-2);
-  border: var(--border-width) solid var(--border-subtle);
-  border-radius: var(--radius-md);
+  min-width: 0;
+  max-width: 100%;
+  padding: var(--space-2) var(--space-3);
+  border: var(--border-width) solid transparent;
+  border-radius: var(--radius-pill);
   background: transparent;
   color: var(--text-body);
   font-family: var(--font-family-mono);
   font-size: var(--font-size-0);
   line-height: var(--line-height-base);
+  overflow-wrap: anywhere;
   cursor: pointer;
 }
 

From ecda0c143269bfcb0507ca120d08067c910403e8 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Mon, 21 Sep 2026 15:22:38 +0200
Subject: [PATCH 071/108] chore(deps): pin html2rss to the test response body

Studio previews need the fetched page on Html2rss::Test::Result, and this revision exposes that reader without putting it on #to_h.
---
 Gemfile      | 2 +-
 Gemfile.lock | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Gemfile b/Gemfile
index 888126d5..92a8b0d3 100644
--- a/Gemfile
+++ b/Gemfile
@@ -7,7 +7,7 @@ git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
 # Pinned by revision, not by branch. This ref is feat/suggest-selector-candidates
 # rebased onto master, so it includes CaptureResult#candidates and the Falcon/HTTPX
 # retry fix. Bump it deliberately; do not swap it for `branch:` or a rubygems constraint.
-gem 'html2rss', github: 'html2rss/html2rss', ref: '281e5e9053f102171bc24d2d7dc018fe4c1871cb'
+gem 'html2rss', github: 'html2rss/html2rss', ref: '628820dbcc55504d0fae160595c6b6bf26bd9d68'
 gem 'html2rss-configs', github: 'html2rss/html2rss-configs'
 
 # Use these instead of the two above (uncomment them) when developing locally:
diff --git a/Gemfile.lock b/Gemfile.lock
index 37b648f0..44376739 100644
--- a/Gemfile.lock
+++ b/Gemfile.lock
@@ -1,7 +1,7 @@
 GIT
   remote: https://github.com/html2rss/html2rss
-  revision: 281e5e9053f102171bc24d2d7dc018fe4c1871cb
-  ref: 281e5e9053f102171bc24d2d7dc018fe4c1871cb
+  revision: 628820dbcc55504d0fae160595c6b6bf26bd9d68
+  ref: 628820dbcc55504d0fae160595c6b6bf26bd9d68
   specs:
     html2rss (0.30.0)
       addressable (~> 2.7)

From 211d8719486237d39493d68869d1a2a953f67c23 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Mon, 21 Sep 2026 15:36:49 +0200
Subject: [PATCH 072/108] feat(studio): re-extract previews from the cached
 page

A later preview of the same canonical URL replays the stored page through local_file. A different URL fetches again, and an empty or failed body does not replace the stored page.
---
 app/web/api/v1/preview_feed.rb       |   5 +-
 app/web/api/v1/preview_page_cache.rb | 125 +++++++++++++++++++++++++++
 spec/html2rss/web/api/v1_spec.rb     |  63 ++++++++++++++
 3 files changed, 192 insertions(+), 1 deletion(-)
 create mode 100644 app/web/api/v1/preview_page_cache.rb

diff --git a/app/web/api/v1/preview_feed.rb b/app/web/api/v1/preview_feed.rb
index 62232dcc..e0411011 100644
--- a/app/web/api/v1/preview_feed.rb
+++ b/app/web/api/v1/preview_feed.rb
@@ -12,6 +12,7 @@ module V1
         #
         # Builds the config through {Feeds::GeneratorInput} and selects
         # {Html2rss::Test::Result} fields. Never forwards +#to_h+, which includes +rss:+.
+        # A later preview of the same canonical URL is replayed by {PreviewPageCache}.
         module PreviewFeed
           # Gem samples stay at three items. Authenticated meadow size is owned here.
           SAMPLE_LIMIT = 10
@@ -24,7 +25,9 @@ def call(request)
               account = StudioRequest.ensure_allowed!(request, live_fetch: true)
               body = StudioRequest.json_object(request)
               url = allowed_url(body['url'], account)
-              result = Html2rss.test(preview_config(url, body['selectors']), min_items: 1)
+              config = PreviewPageCache.replay(url, preview_config(url, body['selectors']))
+              result = Html2rss.test(config, min_items: 1)
+              PreviewPageCache.store(url, result)
               Response.success(response: request.response, data: preview_fields(result))
             end
 
diff --git a/app/web/api/v1/preview_page_cache.rb b/app/web/api/v1/preview_page_cache.rb
new file mode 100644
index 00000000..7aec8f22
--- /dev/null
+++ b/app/web/api/v1/preview_page_cache.rb
@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require 'tempfile'
+
+module Html2rss
+  module Web
+    module Api
+      module V1
+        ##
+        # One process-local HTML page for studio preview replay.
+        #
+        # Keyed by the canonical URL {PreviewFeed} already allowed. A different
+        # URL replaces the slot after a successful fetch. Empty or failed bodies
+        # leave the stored page in place. The temp path is written here.
+        module PreviewPageCache
+          Slot = Data.define(:url, :path)
+          MUTEX = Mutex.new
+
+          class << self
+            ##
+            # @param url [String] canonical page URL
+            # @param config [Hash{Symbol=>Object}] token config from {Feeds::GeneratorInput.for_token}
+            # @return [Hash{Symbol=>Object}] +config+, overlaid with +:local_file+ on a hit
+            def replay(url, config)
+              path = path_for(url)
+              return config unless path
+
+              overlay(config, path)
+            end
+
+            ##
+            # @param url [String] canonical page URL
+            # @param result [Html2rss::Test::Result]
+            # @return [void]
+            def store(url, result)
+              body = storable_body(result)
+              return unless body
+
+              publish(url, write_body(body))
+            end
+
+            ##
+            # Drops the slot and its temp file.
+            #
+            # @return [void]
+            def clear!
+              publish_slot(nil)
+            end
+
+            private
+
+            # @param url [String]
+            # @return [String, nil]
+            def path_for(url)
+              MUTEX.synchronize do
+                current = @slot
+                current.path if current&.url == url && File.file?(current.path)
+              end
+            end
+
+            # @param config [Hash{Symbol=>Object}]
+            # @param path [String]
+            # @return [Hash{Symbol=>Object}]
+            def overlay(config, path)
+              request = config[:request].is_a?(Hash) ? config[:request].dup : {}
+              config.merge(strategy: :local_file, request: request.merge(local_file_path: path))
+            end
+
+            # A failed extraction and a blank page are not a new cached document.
+            #
+            # @param result [Html2rss::Test::Result]
+            # @return [String, nil]
+            def storable_body(result)
+              return unless result.success
+
+              body = result.response_body
+              return unless body.is_a?(String)
+              return if body.strip.empty?
+
+              body
+            end
+
+            # @param url [String]
+            # @param path [String]
+            # @return [void]
+            def publish(url, path)
+              publish_slot(Slot.new(url:, path:))
+            end
+
+            # @param slot [Slot, nil]
+            # @return [void]
+            def publish_slot(slot)
+              previous = nil
+              MUTEX.synchronize do
+                previous = @slot
+                @slot = slot
+              end
+              unlink(previous.path) if previous && previous.path != slot&.path
+            end
+
+            # @param body [String]
+            # @return [String]
+            def write_body(body)
+              file = Tempfile.create(['preview-page-', '.html'])
+              file.write(body)
+              file.path
+            ensure
+              file&.close
+            end
+
+            # @param path [String, nil]
+            # @return [void]
+            def unlink(path)
+              File.unlink(path) if path
+            rescue Errno::ENOENT
+              nil
+            end
+          end
+
+          private_constant :Slot, :MUTEX
+        end
+      end
+    end
+  end
+end
diff --git a/spec/html2rss/web/api/v1_spec.rb b/spec/html2rss/web/api/v1_spec.rb
index f93fc995..55f5bad0 100644
--- a/spec/html2rss/web/api/v1_spec.rb
+++ b/spec/html2rss/web/api/v1_spec.rb
@@ -1007,9 +1007,51 @@ def expected_capped_rows
     end
 
     before do
+      Html2rss::Web::Api::V1::PreviewPageCache.clear!
       allow(Html2rss).to receive(:test).and_return(preview_result)
     end
 
+    after do
+      Html2rss::Web::Api::V1::PreviewPageCache.clear!
+    end
+
+    def post_preview(url)
+      header 'Authorization', "Bearer #{admin_token}"
+      header 'Content-Type', 'application/json'
+      post '/api/v1/feeds/preview', { url:, selectors: { items: { selector: 'article' } } }.to_json
+    end
+
+    def preview_strategy
+      name = Html2rss::Config.default_strategy_name.to_s
+      (name.strip.empty? ? 'auto' : name).to_sym
+    end
+
+    def record_preview_results(results)
+      pending = results.dup
+      configs = []
+      cached_pages = []
+      allow(Html2rss).to receive(:test) do |config, **|
+        path = config.dig(:request, :local_file_path)
+        cached_pages << (path && File.file?(path) ? File.read(path) : nil)
+        configs << config
+        pending.shift || preview_result
+      end
+      [configs, cached_pages]
+    end
+
+    def kept_page_result
+      preview_result.with(response_body: '<html>kept</html>')
+    end
+
+    def rejected_page_results
+      [
+        kept_page_result,
+        failed_preview_result.with(response_body: '<html>failed</html>'),
+        preview_result.with(response_body: '   '),
+        kept_page_result
+      ]
+    end
+
     it 'selects test fields and never returns the rss body', :aggregate_failures do
       header 'Authorization', "Bearer #{admin_token}"
       header 'Content-Type', 'application/json'
@@ -1068,6 +1110,27 @@ def expected_capped_rows
       expect(json.dig('data', 'sample_items', 0)).not_to have_key('image')
     end
 
+    it 'replays the same url from the cached page and fetches a different url', :aggregate_failures do
+      configs, pages = record_preview_results([kept_page_result, kept_page_result, kept_page_result])
+      post_preview(feed_url)
+      post_preview(feed_url)
+      post_preview('https://other.example/news')
+
+      expect(configs.map { it[:strategy] }).to eq([preview_strategy, :local_file, preview_strategy])
+      expect(pages[1]).to eq('<html>kept</html>')
+    end
+
+    it 'keeps the stored page when a later body is empty or failed', :aggregate_failures do
+      configs, pages = record_preview_results(rejected_page_results)
+      post_preview(feed_url)
+      post_preview(feed_url)
+      post_preview('https://other.example/empty')
+      post_preview(feed_url)
+
+      expect(configs.map { it[:strategy] }).to eq([preview_strategy, :local_file, preview_strategy, :local_file])
+      expect(pages.values_at(1, 3)).to eq(['<html>kept</html>', '<html>kept</html>'])
+    end
+
     it 'previews through the token generator config' do
       header 'Authorization', "Bearer #{admin_token}"
       header 'Content-Type', 'application/json'

From cff585efe7e1673357865cd7e97f6ca4ee831e4a Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Mon, 21 Sep 2026 15:52:34 +0200
Subject: [PATCH 073/108] feat(studio): keep refinement on the result and
 export the page URL

Drop the standalone refine route so selector edits stay on the result page, and write channel.url into View as YAML so the copied config can run.
---
 AGENTS.md                                     |   2 +-
 CONTEXT.md                                    |   2 +-
 app/web/api/v1/preview_feed.rb                |  14 +-
 app/web/api/v1/studio_request.rb              |  39 ++++
 app/web/api/v1/suggest_selectors.rb           |  14 +-
 app/web/api/v1/validate_config.rb             |  48 +++--
 docs/README.md                                |   2 +-
 docs/design-system.md                         |   7 +-
 docs/personas.md                              |  14 +-
 frontend/e2e/smoke.spec.ts                    |  19 +-
 frontend/src/__tests__/ConfigStudio.test.tsx  |  26 +--
 frontend/src/__tests__/ResultDisplay.test.tsx | 169 ------------------
 frontend/src/__tests__/apiHttp.feeds.test.ts  |   2 +-
 frontend/src/__tests__/appRoute.test.ts       |  16 +-
 frontend/src/__tests__/decideJourney.test.ts  |  37 ----
 frontend/src/__tests__/mocks/apiFixtures.ts   |  14 +-
 frontend/src/__tests__/mocks/server.ts        |   7 +-
 frontend/src/__tests__/useFeedFlow.test.ts    |  46 -----
 frontend/src/__tests__/useStudio.test.ts      |  19 +-
 frontend/src/api/generated/types.gen.ts       |   1 +
 frontend/src/api/http/feeds.ts                |   3 +-
 frontend/src/components/App.tsx               |  16 --
 frontend/src/components/AppPanels.tsx         |  38 +---
 frontend/src/components/ConfigStudio.tsx      |  87 +++------
 frontend/src/components/ResultDisplay.tsx     |   1 -
 frontend/src/feed/decideJourney.ts            |   9 +-
 frontend/src/feed/useFeedFlow.ts              |  24 ---
 frontend/src/journey/copy.ts                  |   4 +-
 frontend/src/routes/appRoute.ts               |  14 --
 frontend/src/studio/studioService.ts          |   6 +-
 frontend/src/studio/useStudio.ts              |  11 +-
 public/openapi.yaml                           |   2 +
 spec/html2rss/web/api/v1_spec.rb              |  23 ++-
 33 files changed, 217 insertions(+), 519 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index c38b0b4a..2431acd5 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -87,7 +87,7 @@ Token-holder refinement of the selectors subtree, then generate via create.
 | Disabled response | `403` when the flag is off                                                                                                            |
 | Auth              | Access token required on validate, preview, suggest, and create                                                                       |
 | Live fetch        | Preview and suggest also need `AUTO_SOURCE_ENABLED`                                                                                   |
-| Frontend          | Successful results refine inline on `#/result/:token`. `#/refine` is only authenticated extraction-empty recovery. A successful in-memory result replaces `#/refine` with that result. Missing URL, studio-off, or tokenless bounces to remounted `#/create` |
+| Frontend          | Successful results refine inline on `#/result/:token`. There is no `#/refine` route. Empty URL recovers onto remounted `#/create` |
 | Contract SSOT     | Request specs under `spec/html2rss/web/api/v1_spec.rb` and generated `public/openapi.yaml`                                            |
 
 After handler or envelope changes: `make openapi` and `make ci-ready`.
diff --git a/CONTEXT.md b/CONTEXT.md
index 60027b43..0a303802 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -29,7 +29,7 @@ On create, `findCatalogEntries` matches the typed query against the catalog (URL
 Visiting create (including hashbang `#!/…` → `#/…`) bumps `createEntryKey` so the create surface remounts. Remount alone does not auto-submit; auto-submit requires `prefillUrl`.
 
 ### Config Studio
-Selector refinement for a token holder when studio is enabled. On a successful result, refinement is available on demand behind demoted **Refine selectors** on `#/result/:token` (collapsed by default; one meadow; live studio output replaces the result preview when expanded). `#/refine` is only extraction-empty recovery when no result exists. Memory-bound to the in-memory page URL (no token in the route). The visual builder and YAML are one document; only `studioService` unwraps the studio envelope and maps ranked `candidates` (items / title / link / published) into domain suggestion buckets. Candidates never auto-apply. Chips add or remove selector parts on the authored comma-joined string; suggest does not write that string, and chips do not change Enhance. Field extractors remain fixed by the draft mapper. Save posts refined selectors through Creation IO and stays on the result view.
+Selector refinement for a token holder when studio is enabled. On a successful result, refinement is available on demand behind demoted **Refine selectors** on `#/result/:token` (collapsed by default; one meadow; live studio output replaces the result preview after an edit). The page URL leads the controls. The visual builder and YAML are one document: validate exports `channel.url` plus selectors. Only `studioService` unwraps the studio envelope and maps ranked `candidates` (items / title / link / published) into domain suggestion buckets. Candidates never auto-apply. Chips add or remove selector parts on the authored comma-joined string; suggest does not write that string, and chips do not change Enhance. Field extractors remain fixed by the draft mapper. Save posts refined selectors through Creation IO and stays on the result view.
 
 ### Refined Selectors
 The allowlisted `selectors` document a token holder may attach on feed creation. Signed into the feed token and resolved on later serves. Not a full config: channel, headers, and strategy stay denied.
diff --git a/app/web/api/v1/preview_feed.rb b/app/web/api/v1/preview_feed.rb
index e0411011..ee00a87f 100644
--- a/app/web/api/v1/preview_feed.rb
+++ b/app/web/api/v1/preview_feed.rb
@@ -24,7 +24,7 @@ class << self
             def call(request)
               account = StudioRequest.ensure_allowed!(request, live_fetch: true)
               body = StudioRequest.json_object(request)
-              url = allowed_url(body['url'], account)
+              url = StudioRequest.allowed_url(body['url'], account)
               config = PreviewPageCache.replay(url, preview_config(url, body['selectors']))
               result = Html2rss.test(config, min_items: 1)
               PreviewPageCache.store(url, result)
@@ -33,18 +33,6 @@ def call(request)
 
             private
 
-            # @param raw_url [String, nil]
-            # @param account [Hash]
-            # @return [String]
-            def allowed_url(raw_url, account)
-              url = UrlValidator.canonical_url(raw_url.to_s.strip)
-              raise BadRequestError, 'URL parameter is required' if raw_url.to_s.strip.empty?
-              raise BadRequestError, 'Invalid URL format' unless url
-              raise ForbiddenError, 'URL not allowed for this account' unless UrlValidator.url_allowed?(account, url)
-
-              url
-            end
-
             # @param url [String]
             # @param selectors [Object]
             # @return [Hash{Symbol=>Object}]
diff --git a/app/web/api/v1/studio_request.rb b/app/web/api/v1/studio_request.rb
index 4103cc52..1068305d 100644
--- a/app/web/api/v1/studio_request.rb
+++ b/app/web/api/v1/studio_request.rb
@@ -26,6 +26,34 @@ def ensure_allowed!(request, live_fetch: false)
               account
             end
 
+            ##
+            # Canonical page URL the account is allowed to reach.
+            #
+            # @param raw_url [Object]
+            # @param account [Hash]
+            # @return [String]
+            def allowed_url(raw_url, account)
+              stripped = raw_url.to_s.strip
+              raise BadRequestError, 'URL parameter is required' if stripped.empty?
+
+              require_allowed_url(stripped, account)
+            end
+
+            ##
+            # Canonical page URL when the caller sent one.
+            #
+            # A blank value is absent. A present value that cannot be used raises.
+            #
+            # @param raw_url [Object]
+            # @param account [Hash]
+            # @return [String, nil]
+            def page_url(raw_url, account)
+              stripped = raw_url.to_s.strip
+              return if stripped.empty?
+
+              require_allowed_url(stripped, account)
+            end
+
             ##
             # Parses a size-bounded JSON request body as an object.
             #
@@ -45,6 +73,17 @@ def json_object(request)
 
             private
 
+            # @param stripped [String]
+            # @param account [Hash]
+            # @return [String]
+            def require_allowed_url(stripped, account)
+              url = UrlValidator.canonical_url(stripped)
+              raise BadRequestError, 'Invalid URL format' unless url
+              raise ForbiddenError, 'URL not allowed for this account' unless UrlValidator.url_allowed?(account, url)
+
+              url
+            end
+
             # @param request [Rack::Request]
             # @return [String]
             def read_body(request)
diff --git a/app/web/api/v1/suggest_selectors.rb b/app/web/api/v1/suggest_selectors.rb
index afbc0489..f23a5bed 100644
--- a/app/web/api/v1/suggest_selectors.rb
+++ b/app/web/api/v1/suggest_selectors.rb
@@ -21,7 +21,7 @@ def call(request)
               account = StudioRequest.ensure_allowed!(request, live_fetch: true)
               body = StudioRequest.json_object(request)
               captured = Html2rss.capture(
-                allowed_url(body['url'], account),
+                StudioRequest.allowed_url(body['url'], account),
                 strategy: :auto,
                 items_selector: hint(body['items_selector'])
               )
@@ -30,18 +30,6 @@ def call(request)
 
             private
 
-            # @param raw_url [String, nil]
-            # @param account [Hash]
-            # @return [String]
-            def allowed_url(raw_url, account)
-              url = UrlValidator.canonical_url(raw_url.to_s.strip)
-              raise BadRequestError, 'URL parameter is required' if raw_url.to_s.strip.empty?
-              raise BadRequestError, 'Invalid URL format' unless url
-              raise ForbiddenError, 'URL not allowed for this account' unless UrlValidator.url_allowed?(account, url)
-
-              url
-            end
-
             # @param raw [Object]
             # @return [String, nil]
             # @raise [Html2rss::Web::BadRequestError] when the hint exceeds the cap
diff --git a/app/web/api/v1/validate_config.rb b/app/web/api/v1/validate_config.rb
index d7af6c52..5c3dc38c 100644
--- a/app/web/api/v1/validate_config.rb
+++ b/app/web/api/v1/validate_config.rb
@@ -18,27 +18,30 @@ class << self
             # @param request [Rack::Request]
             # @return [Hash{Symbol=>Object}]
             def call(request)
-              StudioRequest.ensure_allowed!(request)
+              account = StudioRequest.ensure_allowed!(request)
               body = StudioRequest.json_object(request)
-              report, selectors = assess(body)
-              Response.success(response: request.response, data: payload(report, selectors))
+              url = StudioRequest.page_url(body['url'], account)
+              report, selectors = assess(body, url)
+              Response.success(response: request.response, data: payload(report, selectors, url))
             end
 
             private
 
             # @param body [Hash]
+            # @param url [String, nil]
             # @return [Array(Html2rss::Config::ValidationReport, Hash, nil)]
-            def assess(body)
-              return assess_yaml(body['yaml']) if body.key?('yaml') && !body['yaml'].nil?
+            def assess(body, url)
+              return assess_yaml(body['yaml'], url) if body.key?('yaml') && !body['yaml'].nil?
               raise BadRequestError, 'yaml or selectors is required' unless body.key?('selectors')
 
-              assess_fragment(body)
+              assess_fragment({ selectors: body['selectors'] }, url)
             end
 
             # @param yaml [Object]
+            # @param url [String, nil]
             # @return [Array(Html2rss::Config::ValidationReport, Hash, nil)]
-            def assess_yaml(yaml)
-              assess_fragment(Html2rss::Config.from_yaml(yaml.to_s))
+            def assess_yaml(yaml, url)
+              assess_fragment(Html2rss::Config.from_yaml(yaml.to_s), url)
             rescue ArgumentError, Psych::Exception => error
               [Html2rss::Config::IssueMapper.parse_failure(error.message), nil]
             end
@@ -47,27 +50,42 @@ def assess_yaml(yaml)
             # rejects (denied or unknown root key, oversized wire) stays a 400.
             #
             # @param fragment [Hash]
+            # @param url [String, nil]
             # @return [Array(Html2rss::Config::ValidationReport, Hash, nil)]
-            def assess_fragment(fragment)
+            def assess_fragment(fragment, url)
               refined = RefinedSelectors.from_client(fragment)
-              [validation_report(refined.selectors), refined.selectors]
+              [validation_report(refined.selectors, url), refined.selectors]
             rescue RefinedSelectors::SchemaInvalid => error
               selectors = fragment.is_a?(Hash) ? fragment[:selectors] || fragment['selectors'] : nil
               [error.report, selectors.is_a?(Hash) ? selectors : nil]
             end
 
+            # The gem validator needs a channel URL. The export uses the caller's
+            # page URL and never the placeholder.
+            #
             # @param selectors [Hash, nil]
+            # @param url [String, nil]
             # @return [Html2rss::Config::ValidationReport]
-            def validation_report(selectors)
-              Html2rss::Config.validate({ channel: { url: PLACEHOLDER_URL }, selectors: selectors || {} })
+            def validation_report(selectors, url)
+              Html2rss::Config.validate({ channel: { url: url || PLACEHOLDER_URL }, selectors: selectors || {} })
             end
 
             # @param report [Html2rss::Config::ValidationReport]
             # @param selectors [Hash, nil]
+            # @param url [String, nil]
             # @return [Hash{Symbol=>Object}]
-            def payload(report, selectors)
-              yaml = selectors.is_a?(Hash) ? Html2rss::Config.to_yaml({ selectors: }) : nil
-              { report: report.to_h, selectors:, yaml: }
+            def payload(report, selectors, url)
+              { report: report.to_h, selectors:, yaml: export_yaml(selectors, url) }
+            end
+
+            # @param selectors [Hash, nil]
+            # @param url [String, nil]
+            # @return [String, nil]
+            def export_yaml(selectors, url)
+              return unless selectors.is_a?(Hash)
+
+              document = url ? { channel: { url: }, selectors: } : { selectors: }
+              Html2rss::Config.to_yaml(document)
             end
           end
         end
diff --git a/docs/README.md b/docs/README.md
index 985148f3..66ff8b62 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -212,7 +212,7 @@ Rules:
 - `BUILD_TAG` and `GIT_SHA` are required in production so startup logs can identify the deployed build.
 - Add or change flags in code, tests, and this table together.
 
-`STUDIO_ENABLED=true` exposes the config refinement studio: `POST /api/v1/feeds/validate`, `POST /api/v1/feeds/preview`, and `POST /api/v1/feeds/suggest_selectors`. All three require a valid access token and return `403 Studio is disabled` when the flag is off. `POST /api/v1/feeds` returns the same `403` when the body carries a `selectors` object, because those selectors are studio output; a body without `selectors` stays the automatic path and keeps working with the flag off. `preview` and `suggest_selectors` additionally need `AUTO_SOURCE_ENABLED=true` because they fetch the caller's URL live, and they only accept URLs the caller's account is allowed to reach. Authenticated preview samples are capped at 10 items and include only safe HTTP(S) image URLs. `GET /api/v1` advertises `instance.studio.enabled` so the SPA can hide selector controls and the extraction-empty Refine action when the flag is off, and bounce `#/refine` to create. A successful in-memory result keeps refinement on `#/result/:token`. Leave the flag off in production unless you intend to let token holders run live extraction against arbitrary allowed URLs.
+`STUDIO_ENABLED=true` exposes the config refinement studio: `POST /api/v1/feeds/validate`, `POST /api/v1/feeds/preview`, and `POST /api/v1/feeds/suggest_selectors`. All three require a valid access token and return `403 Studio is disabled` when the flag is off. `POST /api/v1/feeds` returns the same `403` when the body carries a `selectors` object, because those selectors are studio output; a body without `selectors` stays the automatic path and keeps working with the flag off. `preview` and `suggest_selectors` additionally need `AUTO_SOURCE_ENABLED=true` because they fetch the caller's URL live, and they only accept URLs the caller's account is allowed to reach. Validate accepts the same page URL and, when it is present and allowed, exports it as `channel.url` beside the selectors. Authenticated preview samples are capped at 10 items and include only safe HTTP(S) image URLs. `GET /api/v1` advertises `instance.studio.enabled` so the SPA can hide selector controls when the flag is off. Refinement stays on `#/result/:token`. Leave the flag off in production unless you intend to let token holders run live extraction against arbitrary allowed URLs.
 
 Rate limiting still uses the shared `RATE_LIMIT_MAX_REQUESTS` budget over `RATE_LIMIT_WINDOW_SECONDS`, but each live-fetch studio request to `preview` or `suggest_selectors` consumes five request slots. This fixed weighting protects the more expensive HTTP/browser extraction paths without adding another deployment flag.
 
diff --git a/docs/design-system.md b/docs/design-system.md
index 2db24d5f..47a16d2c 100644
--- a/docs/design-system.md
+++ b/docs/design-system.md
@@ -40,12 +40,11 @@ If a page looks like it came from a different product, the change is wrong even
 
 - **Create:** URL field is the task. Visiting `#/create` or `#!/create` remounts create; hashbang aliases canonicalize to `#/create`. Bare create does not auto-submit. When the typed query finds catalog entries (URL equivalence or text substring), show matching feeds as a subordinate list under the field — never a second primary task or in-app catalog browser. On an empty Create URL, up to three Feed Directory starters may appear as subordinate chrome (lean: `.ui-eyebrow` + list + demoted `utility-link` escape under the list when creation is enabled; Notice when creation is disabled). Escape and utility-strip share **Browse Feed Directory (N)** (`catalogEntries.length`); hide starters and the under-list escape while typing, when find has hits, or while creating.
 - **Token gate:** a native `<dialog>` over the still-mounted, inert URL task (one interactive task). Auth copy is in-field (`tokenError`); ActionFeedback stays on create. Access Token persists until Logout with no storage UI.
-- **Result:** primary CTA is **Copy feed URL**, and it takes initial focus. Open feed / JSON / feed-reader are demoted secondary actions and stay available while preview loads. Preview is one meadow and non-blocking confirmation only. Guest results stay compact: at most 5 items, no images, no selector controls. An authenticated, studio-enabled result keeps that same frame: a demoted **Refine selectors** action in `ui-actions` (collapsed by default). Opening it mounts selector controls **above** the meadow; closing it returns to the static meadow without discarding the in-memory draft. Studio validate/preview/suggest do not run until the panel opens. Selector edits keep the previous meadow visible and mark it loading until live studio output replaces it. They do not add a second list, and they do not return to the create-time meadow once a studio sample exists. Until that sample exists, including while the first studio preview loads, the result keeps its create-time meadow. The studio meadow is captioned as the page already fetched for this URL. **Save and generate feed** is the only primary action inside those controls. Member previews may show up to 10 items and safe HTTP(S) images.
-- **Empty extraction:** **Refine selectors** is one quiet action beside Try again when the extraction is empty, studio is enabled, and an access token is present. It is not offered for other create errors, guests, or a studio-off instance.
-- **Refine:** `#/refine` is memory-bound extraction-empty recovery for an authenticated studio (see [personas.md](personas.md) J2). No token in the route. A successful in-memory result replaces `#/refine` with `#/result/:token`; refinement of that feed stays on the result behind the same demoted **Refine selectors** gate. Standalone recovery uses the same frame as an expanded Result: a `result-shell` / `layout-stack` rail — never a mega-card bisected by the fixed footer, never a two-column paddock. First viewport leads with compact controls (items selector, ranked **Selector choices** per bucket as wrapping add/remove pills, a large Enhance hit target, and **Save and generate feed** as the only `btn--primary` in `ui-actions`), then the live preview meadow (`.ui-item-list`) after validation. URL, native-feed Notice, and View as YAML are demoted support below the meadow. Changing the URL re-suggests and re-previews without leaving the current surface or running catalog find; empty URL recovers onto remounted `#/create`. Ranked candidates (items, title, link, published) are wrapping pills on the authored selector: `--radius-pill`, `--space-2`/`--space-3` padding, a transparent outline when idle, and `--surface-elevated` with `--border-strong` when pressed. A pill and its list item use `min-width: 0` and `max-width: 100%`; the pill uses `overflow-wrap: anywhere`. A pill adds or removes its selector parts in the comma-joined draft string; suggest does not write that string. Pills do not change Enhance. Empty buckets stay hidden. Wire is the typed closed selectors document (no strip/trim/affix cleanup UI). Fix a field opens one selector panel **in the stack** for Title, Link, or Published date. View as YAML is read-only and captioned as a selectors fragment — not a feeds.yml. Save-failure Notices use wire `Decision#message` — never create-journey copy. When studio is disabled or the caller has no token, Refine actions stay hidden and `#/refine` bounces to create. Focus on standalone recovery is the items selector; a successful Result keeps focus on Copy whether Refine is open or closed.
+- **Result:** primary CTA is **Copy feed URL**, and it takes initial focus. Open feed / JSON / feed-reader are demoted secondary actions and stay available while preview loads. Preview is one meadow and non-blocking confirmation only. Guest results stay compact: at most 5 items, no images, no selector controls. An authenticated, studio-enabled result keeps that same frame: a demoted **Refine selectors** action in `ui-actions` (collapsed by default). Opening it mounts selector controls **above** the meadow; closing it returns to the static meadow without discarding the in-memory draft. The page URL leads those controls, then the items selector, ranked **Selector choices**, Enhance, and **Save and generate feed** as the only `btn--primary` inside the panel. Studio validate/preview/suggest do not run until the panel opens, and the first live preview waits for an edit so the create-time meadow stays single. Selector edits keep the previous meadow visible and mark it loading until live studio output replaces it. They do not add a second list, and they do not return to the create-time meadow once a studio sample exists. Until that sample exists, including while the first studio preview loads, the result keeps its create-time meadow. The studio meadow is captioned as the page already fetched for this URL. Member previews may show up to 10 items and safe HTTP(S) images. A native-feed Notice and **View as YAML** sit below the meadow. View as YAML is read-only `channel.url` plus selectors for this page. Changing the URL re-suggests and re-previews without leaving the result or running catalog find; an empty URL recovers onto remounted `#/create`. There is no `#/refine` route. Ranked candidates (items, title, link, published) are wrapping pills on the authored selector: `--radius-pill`, `--space-2`/`--space-3` padding, a transparent outline when idle, and `--surface-elevated` with `--border-strong` when pressed. A pill and its list item use `min-width: 0` and `max-width: 100%`; the pill uses `overflow-wrap: anywhere`. A pill adds or removes its selector parts in the comma-joined draft string; suggest does not write that string. Pills do not change Enhance. Empty buckets stay hidden. Wire is the typed closed selectors document (no strip/trim/affix cleanup UI). Fix a field opens one selector panel **in the stack** for Title, Link, or Published date. Save-failure Notices use wire `Decision#message`. When studio is disabled or the caller has no token, Refine stays hidden. Focus stays on Copy whether Refine is open or closed.
+- **Empty extraction:** a create error. **Try again** when the decision is retryable. Selector refinement stays on a successful result.
 - **Unmatched result:** `#/result/:token` is valid only with a matching in-memory result. Missing or mismatched tokens recover onto remounted `#/create` (no API rehydrate, no failure chrome, no durable shareable result page).
 - **Status eyebrow:** one vocabulary (`Feed ready`) on the result header; preview progress lives in the preview section.
-- **Focus:** create autofocuses the URL field; token autofocuses the token field; result focuses the Copy control; standalone extraction-empty refine focuses the items selector.
+- **Focus:** create autofocuses the URL field; token autofocuses the token field; result focuses the Copy control.
 
 ### Vocabulary
 
diff --git a/docs/personas.md b/docs/personas.md
index c9f72117..a7a79210 100644
--- a/docs/personas.md
+++ b/docs/personas.md
@@ -10,7 +10,7 @@ Related: [design-system.md](design-system.md) Journey Grammar (SPA chrome), [REA
 | --- | --- | --- | --- | --- |
 | **Sam** (SPA primary) | Follow a site that has no feed | SPA: URL → Result → Copy | Create, token, catalog find, refine recovery | YAML authoring, MCP, directory PRs |
 | **Alex** (operator) | Run a private instance | Compose + env flags | Token, catalog, `feeds.yml` mount, `STUDIO_ENABLED` | In-browser config IDE |
-| **Morgan** (AI/MCP) | Agent scrapes and mass-creates feeds for *their* project | Gem MCP (stdio/http) | Optional: loop `POST /api/v1/feeds` to mint **hosted** feed URLs on Alex’s instance | `#/refine` clicks, batch UI, configs repo metadata |
+| **Morgan** (AI/MCP) | Agent scrapes and mass-creates feeds for *their* project | Gem MCP (stdio/http) | Optional: loop `POST /api/v1/feeds` to mint **hosted** feed URLs on Alex’s instance | Result-page selector clicks, batch UI, configs repo metadata |
 | **Riley** (configs maintainer) | Automate directory bureaucracy (recon ledger, catalog fields, quality gate, registry) | html2rss-configs skill + MCP `capture` → `test` → `apply` | Downstream: `GET /api/v1/configs` `last_result` as a repair signal after sync | SPA studio, hosted feed tokens as the source of truth |
 
 Bookmarklet is a **Sam on-ramp**, not a fifth persona.
@@ -20,14 +20,14 @@ Bookmarklet is a **Sam on-ramp**, not a fifth persona.
 - **Job:** Paste a listing URL, get a feed URL, subscribe in a reader.
 - **Owning surface:** html2rss-web SPA.
 - **Golden path:** Create → token (if needed) → Result → **Copy feed URL**.
-- **Recovery only:** wrong list or missing Title/Link/Published (J3) and a wrong listing URL (J3b) stay on Result for a token holder when studio is enabled — behind the same demoted **Refine selectors** quiet action used for **J2** (empty extraction), collapsed by default. `#/refine` is only **J2** when no successful result exists. It is not an authoring product.
+- **Recovery only:** wrong list, missing Title/Link/Published, or a wrong listing URL stay on Result for a token holder when studio is enabled, behind demoted **Refine selectors** (collapsed by default). It is not an authoring product. Empty extraction stays a create error.
 - **Non-goal:** Learning YAML, MCP, or directory contribution through the SPA.
 
 ## Alex — operator
 
 - **Job:** Self-host a private instance with the right flags and mounts.
 - **Owning surface:** Docker Compose / env (`AUTO_SOURCE_ENABLED`, `STUDIO_ENABLED`, `CONFIG_CATALOG_ENABLED`, access token, `feeds.yml`).
-- **html2rss-web role:** Configure capability; when studio is off or the caller has no token, selector controls and Refine stay hidden and `#/refine` bounces to create.
+- **html2rss-web role:** Configure capability. When studio is off or the caller has no token, selector controls and Refine stay hidden. **View as YAML** on an authenticated result is a read-only `channel.url` plus selectors export for that page, suitable to copy into a mounted feed file. It is not a `directory.*` configs PR.
 - **Non-goal:** An in-browser config IDE as a substitute for CLI, MCP, or mounted YAML.
 
 ## Morgan — AI / MCP agent
@@ -35,15 +35,11 @@ Bookmarklet is a **Sam on-ramp**, not a fifth persona.
 - **Job:** Agent-driven scrape and durable feed configs for *their* projects (including mass create).
 - **Owning surface:** html2rss gem MCP — articles now via `scrape` / `batch_scrape`; durable YAML via `capture` → `test` → `apply`.
 - **html2rss-web role (optional):** Authenticated `POST /api/v1/feeds` (and catalog read) to store **hosted** feed URLs on an instance. Selectors belong in MCP first; studio POST bodies are not a second MCP.
-- **Non-goal:** `#/refine`, an SPA batch console, or treating web studio validate/preview/suggest as agent tooling.
+- **Non-goal:** An SPA batch console, or treating web studio validate/preview/suggest as agent tooling.
 
 ## Riley — configs maintainer
 
 - **Job:** Ship curated YAML to html2rss-configs (recon BUILD/DEFER/DROP, `directory.*`, quality gate, registry bundle).
 - **Owning surface:** html2rss-configs skill modes + MCP `capture` → `test` → `apply`, then `registry-build`.
 - **html2rss-web role:** Consumes published bundles; `last_result` on `GET /api/v1/configs` is a repair signal after sync — not an in-app repair dashboard.
-- **Non-goal:** Authoring directory configs in the SPA. **View as YAML** on refine is a selectors fragment, not a `directory.*`-complete configs PR.
-
-## SPA refine scope (Sam only)
-
-`#/refine` is documented only as Sam **J2** extraction-empty recovery. J3 and J3b stay on the authenticated Result. Morgan and Riley journeys never open this screen.
+- **Non-goal:** Authoring directory configs in the SPA. **View as YAML** is `channel.url` plus selectors, not a `directory.*` configs PR.
diff --git a/frontend/e2e/smoke.spec.ts b/frontend/e2e/smoke.spec.ts
index fa417b00..13ea31a1 100644
--- a/frontend/e2e/smoke.spec.ts
+++ b/frontend/e2e/smoke.spec.ts
@@ -211,7 +211,7 @@ test.describe('frontend smoke', () => {
     await expect(page.locator('.result-recovery')).toHaveCount(0);
   });
 
-  test('recovers an empty refine route onto remounted create', async ({ page }) => {
+  test('treats a refine hash as create', async ({ page }) => {
     await stubSpaApi(page, { isCatalogEnabled: false });
 
     await page.goto('/#/refine');
@@ -330,32 +330,23 @@ test.describe('frontend smoke', () => {
     await expect(page.getByRole('button', { name: COPY.createFeed })).toBeVisible();
   });
 
-  test('returns a stale refine hash to the matching in-memory result', async ({ page }) => {
+  test('leaves a result when the hash is the retired refine route', async ({ page }) => {
     await createReadyResult(page);
 
     await page.evaluate(() => {
       location.hash = '#/refine';
     });
 
-    await expect(page).toHaveURL(/\/#\/result\/generated-token$/);
-    await expect(page.locator('.result-shell')).toHaveAttribute('data-state', 'result');
+    await expect(page).toHaveURL(/\/#\/create$/);
+    await expect(page.locator('.form-shell')).toHaveAttribute('data-state', 'create');
     await expect(page.getByRole('heading', { name: COPY.refineSelectors })).toHaveCount(0);
-    await expect(page.getByRole('button', { name: COPY.refineSelectors })).toBeVisible();
-    await expect(page.getByLabel(COPY.itemsSelector, { exact: true })).toHaveCount(0);
   });
 
-  test('hides refine when studio is disabled and bounces forced refine onto create', async ({ page }) => {
+  test('hides refine when studio is disabled', async ({ page }) => {
     await createReadyResult(page, { isStudioEnabled: false });
 
     await expect(page.getByText(COPY.feedReady)).toBeVisible();
     await expect(page.getByRole('button', { name: COPY.refineSelectors })).toHaveCount(0);
     await expect(page.getByRole('button', { name: COPY.createAnother })).toBeVisible();
-
-    await page.goto('/#/refine');
-
-    await expect(page).toHaveURL(/\/#\/create$/);
-    await expect(page.getByLabel(COPY.urlLabel)).toBeVisible();
-    await expect(page.getByRole('heading', { name: COPY.refineSelectors })).toHaveCount(0);
-    await expect(page.locator('.form-shell')).toHaveAttribute('data-state', 'create');
   });
 });
diff --git a/frontend/src/__tests__/ConfigStudio.test.tsx b/frontend/src/__tests__/ConfigStudio.test.tsx
index 6d58dbc4..5a3efcc6 100644
--- a/frontend/src/__tests__/ConfigStudio.test.tsx
+++ b/frontend/src/__tests__/ConfigStudio.test.tsx
@@ -6,6 +6,7 @@ import { server } from './mocks/server';
 import {
   rankedSuggestSuccessBody,
   selectorsFromValidateRequest,
+  pageUrlFrom,
   suggestSuccessBody,
   validateSuccessBody,
   validateYamlForSelectors,
@@ -66,8 +67,10 @@ const previewWithImage = () =>
 function echoValidate() {
   server.use(
     http.post('/api/v1/feeds/validate', async ({ request }) => {
-      const selectors = selectorsFromValidateRequest(await request.json());
-      return HttpResponse.json(validateSuccessBody(selectors, validateYamlForSelectors(selectors)));
+      const body = await request.json();
+      const selectors = selectorsFromValidateRequest(body);
+      const yaml = validateYamlForSelectors(selectors, pageUrlFrom(body));
+      return HttpResponse.json(validateSuccessBody(selectors, yaml));
     })
   );
 }
@@ -121,34 +124,33 @@ async function waitForItemsChip(name = COPY.addSelector('article')) {
 }
 
 describe('ConfigStudio', () => {
-  it('leads with the items selector above the preview meadow when live preview is ready', async () => {
+  it('keeps the page URL and items selector above the preview meadow', async () => {
     echoValidate();
     stubPreview(previewWithImage());
     renderStudio();
 
+    fireEvent.click(await waitForItemsChip());
     await waitFor(() => expect(screen.getByText('With image')).toBeInTheDocument());
 
     const meadow = screen.getByLabelText(COPY.previewRegion);
     const items = screen.getByLabelText(COPY.itemsSelector);
     expect(items.compareDocumentPosition(meadow) & Node.DOCUMENT_POSITION_FOLLOWING).not.toBe(0);
-    expect(document.querySelector('.result-shell')).toHaveAttribute('data-state', 'refine');
     expect(document.querySelector('.ui-card')).toBeNull();
   });
 
-  it('focuses the items selector on a single-rail meadow with an editable URL', async () => {
+  it('keeps one rail with the page URL above the items selector', async () => {
     renderStudio();
 
     const items = screen.getByLabelText(COPY.itemsSelector);
     const urlField = screen.getByLabelText(COPY.urlLabel);
     expect(urlField).toHaveValue(pageUrl);
+    expect(urlField.compareDocumentPosition(items) & Node.DOCUMENT_POSITION_FOLLOWING).not.toBe(0);
     expect(document.querySelector('.refine-columns')).toBeNull();
     expect(screen.getByRole('button', { name: COPY.saveAndGenerate })).toBeDisabled();
     expect(screen.queryByRole('combobox')).not.toBeInTheDocument();
     expect(document.querySelector('textarea')).toBeNull();
     expect(screen.queryByText(/Cleanup/i)).not.toBeInTheDocument();
     expect(screen.queryByText(/Strip HTML/i)).not.toBeInTheDocument();
-    await waitFor(() => expect(items).toHaveFocus());
-    await waitFor(() => expect(items).toHaveValue('a[href]'));
     expect(screen.getByLabelText(COPY.enhanceItems)).toBeInTheDocument();
     await waitFor(() => expect(itemsChip()).toBeInTheDocument());
     expect(screen.getByRole('button', { name: COPY.fieldMissing(COPY.fieldTitle) })).toBeInTheDocument();
@@ -426,6 +428,7 @@ describe('ConfigStudio', () => {
     renderStudio();
 
     expect(screen.queryByRole('button', { name: COPY.previewChecking })).not.toBeInTheDocument();
+    fireEvent.click(await waitForItemsChip());
     await waitFor(() => expect(screen.getByText('Sample headline')).toBeInTheDocument());
     expect(screen.getByRole('link', { name: 'Sample headline' })).toHaveAttribute(
       'href',
@@ -450,6 +453,7 @@ describe('ConfigStudio', () => {
     stubPreview(previewWithImage());
     renderStudio();
 
+    fireEvent.click(await waitForItemsChip());
     await waitFor(() => expect(screen.getByText('With image')).toBeInTheDocument());
     const images = document.querySelectorAll('img.refine-sample-image');
     expect(images).toHaveLength(1);
@@ -468,6 +472,7 @@ describe('ConfigStudio', () => {
     stubPreview(previewWithImage());
     renderStudio(vi.fn(), { token: '  ' });
 
+    fireEvent.click(await waitForItemsChip());
     await waitFor(() => expect(screen.getByText('With image')).toBeInTheDocument());
     expect(document.querySelector('img')).toBeNull();
   });
@@ -486,7 +491,6 @@ describe('ConfigStudio', () => {
 
     render(
       <ConfigStudio
-        placement="inline"
         fallback={<p>Create-time meadow</p>}
         url={pageUrl}
         token="tok"
@@ -522,12 +526,13 @@ describe('ConfigStudio', () => {
     echoValidate();
     server.use(http.post('/api/v1/feeds/preview', () => HttpResponse.error()));
     renderStudio();
+    fireEvent.click(await waitForItemsChip());
 
     expect(await screen.findByRole('button', { name: COPY.checkAgain })).toBeInTheDocument();
     expect(screen.getByText(COPY.previewFetchedCaption)).toBeInTheDocument();
   });
 
-  it('reveals read-only yaml captioned as a selectors fragment', async () => {
+  it('reveals read-only yaml for this page', async () => {
     renderStudio();
     await waitFor(() => expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('a[href]'));
     fireEvent.click(await waitForItemsChip());
@@ -537,7 +542,8 @@ describe('ConfigStudio', () => {
 
     expect(document.querySelector('textarea')).toBeNull();
     await waitFor(() => expect(screen.getByText(/selector: a\[href\], article/)).toBeInTheDocument());
-    expect(screen.getByText(COPY.yamlFragmentCaption)).toBeInTheDocument();
+    expect(screen.getByText(COPY.yamlCaption)).toBeInTheDocument();
+    expect(screen.getByText(/url: https:\/\/example\.com\/articles/)).toBeInTheDocument();
   });
 
   it('sends the validated selectors when generating a feed', async () => {
diff --git a/frontend/src/__tests__/ResultDisplay.test.tsx b/frontend/src/__tests__/ResultDisplay.test.tsx
index d66097bc..60c3ca59 100644
--- a/frontend/src/__tests__/ResultDisplay.test.tsx
+++ b/frontend/src/__tests__/ResultDisplay.test.tsx
@@ -1,10 +1,8 @@
 import { describe, it, expect, beforeEach, vi } from 'vitest';
 import { render, screen, fireEvent, waitFor } from '@testing-library/preact';
 import { ResultDisplay } from '../components/ResultDisplay';
-import { CreateFeedPanel } from '../components/AppPanels';
 import { COPY } from '../journey/copy';
 import type { AppViewModel } from '../feed';
-import type { FeedCreationError } from '../api/contracts';
 
 describe('ResultDisplay', () => {
   const mockOnCreateAnother = vi.fn();
@@ -328,170 +326,3 @@ describe('ResultDisplay', () => {
     expect(screen.getByRole('button', { name: COPY.createAnother })).toBeInTheDocument();
   });
 });
-
-function renderEmptyExtractionError(error: FeedCreationError, onRefine = vi.fn(), onRetryCreate = vi.fn()) {
-  const noop = vi.fn();
-  render(
-    <CreateFeedPanel
-      focusComposerKey={0}
-      viewModel={{
-        kind: 'error',
-        message: error.message,
-        error,
-        errorKind: error.kind,
-      }}
-      isCreating={false}
-      feedFormData={{ url: 'https://example.com/articles' }}
-      feedFieldErrors={{ url: '', form: '' }}
-      submitDisabled={false}
-      feedCreationEnabled
-      studioEnabled
-      hasAccessToken
-      catalogEntries={[]}
-      featuredFeeds={[]}
-      tokenDraft=""
-      onFeedSubmit={noop}
-      onFeedFieldChange={noop}
-      onTokenDraftChange={noop}
-      onSaveToken={noop}
-      onCancelTokenPrompt={noop}
-      onRetryCreate={onRetryCreate}
-      onRefine={onRefine}
-    />
-  );
-
-  return { onRefine, onRetryCreate };
-}
-
-describe('empty extraction refine on-ramp', () => {
-  it('offers refine beside Try again only for an empty extraction', () => {
-    const { onRefine } = renderEmptyExtractionError({
-      kind: 'input',
-      code: 'EXTRACTION_EMPTY',
-      retryable: true,
-      nextAction: 'retry',
-      retryAction: 'primary',
-      message: 'We could not extract feed items from this page yet.',
-    });
-
-    const refine = screen.getByRole('button', { name: COPY.refineSelectors });
-    const tryAgain = screen.getByRole('button', { name: COPY.tryAgain });
-
-    expect(refine).toHaveClass('btn', 'btn--quiet', 'btn--linkish');
-    expect(refine.parentElement).toBe(tryAgain.parentElement);
-    expect(refine.parentElement).toHaveClass('notice__actions');
-
-    fireEvent.click(refine);
-    expect(onRefine).toHaveBeenCalledTimes(1);
-  });
-
-  it('offers refine without Try again when empty extraction is not retryable', () => {
-    renderEmptyExtractionError({
-      kind: 'input',
-      code: 'EXTRACTION_EMPTY',
-      retryable: false,
-      nextAction: 'correct_input',
-      retryAction: 'none',
-      message: 'We could not extract feed items from this page yet.',
-    });
-
-    expect(screen.getByRole('button', { name: COPY.refineSelectors })).toBeInTheDocument();
-    expect(screen.queryByRole('button', { name: COPY.tryAgain })).not.toBeInTheDocument();
-  });
-
-  it('does not offer refine for other create errors', () => {
-    renderEmptyExtractionError({
-      kind: 'input',
-      code: 'BLOCKED_SURFACE',
-      retryable: false,
-      nextAction: 'correct_input',
-      retryAction: 'none',
-      message: 'This site blocked automated access.',
-    });
-
-    expect(screen.queryByRole('button', { name: COPY.refineSelectors })).not.toBeInTheDocument();
-    expect(screen.queryByRole('button', { name: COPY.tryAgain })).not.toBeInTheDocument();
-  });
-
-  it('does not offer refine when studio is disabled', () => {
-    const noop = vi.fn();
-    render(
-      <CreateFeedPanel
-        focusComposerKey={0}
-        viewModel={{
-          kind: 'error',
-          message: 'We could not extract feed items from this page yet.',
-          error: {
-            kind: 'input',
-            code: 'EXTRACTION_EMPTY',
-            retryable: true,
-            nextAction: 'retry',
-            retryAction: 'primary',
-            message: 'We could not extract feed items from this page yet.',
-          },
-          errorKind: 'input',
-        }}
-        isCreating={false}
-        feedFormData={{ url: 'https://example.com/articles' }}
-        feedFieldErrors={{ url: '', form: '' }}
-        submitDisabled={false}
-        feedCreationEnabled
-        studioEnabled={false}
-        hasAccessToken
-        catalogEntries={[]}
-        featuredFeeds={[]}
-        tokenDraft=""
-        onFeedSubmit={noop}
-        onFeedFieldChange={noop}
-        onTokenDraftChange={noop}
-        onSaveToken={noop}
-        onCancelTokenPrompt={noop}
-        onRetryCreate={noop}
-        onRefine={noop}
-      />
-    );
-
-    expect(screen.queryByRole('button', { name: COPY.refineSelectors })).not.toBeInTheDocument();
-  });
-
-  it('does not offer refine without an access token', () => {
-    const noop = vi.fn();
-    render(
-      <CreateFeedPanel
-        focusComposerKey={0}
-        viewModel={{
-          kind: 'error',
-          message: 'We could not extract feed items from this page yet.',
-          error: {
-            kind: 'input',
-            code: 'EXTRACTION_EMPTY',
-            retryable: true,
-            nextAction: 'retry',
-            retryAction: 'primary',
-            message: 'We could not extract feed items from this page yet.',
-          },
-          errorKind: 'input',
-        }}
-        isCreating={false}
-        feedFormData={{ url: 'https://example.com/articles' }}
-        feedFieldErrors={{ url: '', form: '' }}
-        submitDisabled={false}
-        feedCreationEnabled
-        studioEnabled
-        hasAccessToken={false}
-        catalogEntries={[]}
-        featuredFeeds={[]}
-        tokenDraft=""
-        onFeedSubmit={noop}
-        onFeedFieldChange={noop}
-        onTokenDraftChange={noop}
-        onSaveToken={noop}
-        onCancelTokenPrompt={noop}
-        onRetryCreate={noop}
-        onRefine={noop}
-      />
-    );
-
-    expect(screen.queryByRole('button', { name: COPY.refineSelectors })).not.toBeInTheDocument();
-  });
-});
diff --git a/frontend/src/__tests__/apiHttp.feeds.test.ts b/frontend/src/__tests__/apiHttp.feeds.test.ts
index 35ddb43f..56b9b8b6 100644
--- a/frontend/src/__tests__/apiHttp.feeds.test.ts
+++ b/frontend/src/__tests__/apiHttp.feeds.test.ts
@@ -73,7 +73,7 @@ describe('studio JSON writes', () => {
     const fetchMock = vi.spyOn(globalThis, 'fetch').mockResolvedValue(Response.json({ success: true }));
     const selectors = { items: { selector: 'article' } };
 
-    await postValidateFeed('token-123', selectors);
+    await postValidateFeed('token-123', 'https://example.com', selectors);
     await postPreviewFeed('token-123', 'https://example.com', selectors);
     await postSuggestSelectors('token-123', 'https://example.com', 'article');
 
diff --git a/frontend/src/__tests__/appRoute.test.ts b/frontend/src/__tests__/appRoute.test.ts
index a2cb2eca..b17b8d51 100644
--- a/frontend/src/__tests__/appRoute.test.ts
+++ b/frontend/src/__tests__/appRoute.test.ts
@@ -89,14 +89,14 @@ describe('appRoute', () => {
     unmount();
   });
 
-  it('reads refine without a token or prefill URL', () => {
+  it('reads a retired refine hash as create', () => {
     expect(
       readAppRoute({
         pathname: '/',
-        search: '?url=https%3A%2F%2Fexample.com',
+        search: '',
         hash: '#/refine?url=https%3A%2F%2Fexample.com',
       })
-    ).toEqual({ kind: 'refine' });
+    ).toEqual({ kind: 'create', prefillUrl: 'https://example.com' });
 
     expect(
       readAppRoute({
@@ -104,18 +104,16 @@ describe('appRoute', () => {
         search: '',
         hash: '#/refine/',
       })
-    ).toEqual({ kind: 'refine' });
-
-    expect(buildAppRouteHref({ kind: 'refine' }, 'http://localhost/')).toBe('http://localhost/#/refine');
+    ).toEqual({ kind: 'create' });
   });
 
-  it('canonicalizes hashbang refine hashes to #/refine', () => {
+  it('canonicalizes a hashbang refine hash onto create', () => {
     history.replaceState({}, '', 'http://localhost:3000/#!/refine');
 
     const { result, unmount } = renderHook(() => useAppRoute());
 
-    expect(location.hash).toBe('#/refine');
-    expect(result.current.route).toEqual({ kind: 'refine' });
+    expect(location.hash).toBe('#/create');
+    expect(result.current.route).toEqual({ kind: 'create' });
     unmount();
   });
 });
diff --git a/frontend/src/__tests__/decideJourney.test.ts b/frontend/src/__tests__/decideJourney.test.ts
index cd6b9afc..9e0ef9af 100644
--- a/frontend/src/__tests__/decideJourney.test.ts
+++ b/frontend/src/__tests__/decideJourney.test.ts
@@ -10,7 +10,6 @@ describe('decideJourney', () => {
         feedFieldErrors: emptyErrors,
         isCreating: false,
         route: { kind: 'create' },
-        sourceUrl: '',
         tokenError: '',
       })
     ).toEqual({ kind: 'create' });
@@ -21,7 +20,6 @@ describe('decideJourney', () => {
       feedFieldErrors: emptyErrors,
       isCreating: false,
       route: { kind: 'result', feedToken: 'token' },
-      sourceUrl: 'https://example.com',
       tokenError: '',
       result: {
         feed: {
@@ -51,7 +49,6 @@ describe('decideJourney', () => {
         feedFieldErrors: emptyErrors,
         isCreating: false,
         route: { kind: 'result', feedToken: 'route-token' },
-        sourceUrl: '',
         tokenError: '',
         result: {
           feed: {
@@ -75,7 +72,6 @@ describe('decideJourney', () => {
         feedFieldErrors: emptyErrors,
         isCreating: false,
         route: { kind: 'result', feedToken: 'route-token' },
-        sourceUrl: '',
         tokenError: '',
       })
     ).toEqual({ kind: 'create' });
@@ -87,7 +83,6 @@ describe('decideJourney', () => {
         feedFieldErrors: emptyErrors,
         isCreating: true,
         route: { kind: 'create' },
-        sourceUrl: '',
         tokenError: '',
       })
     ).toEqual({ kind: 'submitting' });
@@ -97,7 +92,6 @@ describe('decideJourney', () => {
         feedFieldErrors: { url: '', form: 'Bad url' },
         isCreating: false,
         route: { kind: 'create' },
-        sourceUrl: '',
         tokenError: '',
         creationError: {
           kind: 'input',
@@ -117,39 +111,8 @@ describe('decideJourney', () => {
         feedFieldErrors: emptyErrors,
         isCreating: true,
         route: { kind: 'token' },
-        sourceUrl: 'https://example.com',
         tokenError: '',
       })
     ).toEqual({ kind: 'token_prompt', tokenError: '' });
   });
-
-  it('keeps refine only while an in-memory URL exists', () => {
-    expect(
-      decideJourney({
-        feedFieldErrors: emptyErrors,
-        isCreating: false,
-        route: { kind: 'refine' },
-        sourceUrl: 'https://example.com/articles',
-        tokenError: '',
-        creationError: {
-          kind: 'input',
-          code: 'EXTRACTION_EMPTY',
-          retryable: false,
-          nextAction: 'correct_input',
-          retryAction: 'none',
-          message: 'Empty',
-        },
-      })
-    ).toEqual({ kind: 'refine' });
-
-    expect(
-      decideJourney({
-        feedFieldErrors: emptyErrors,
-        isCreating: false,
-        route: { kind: 'refine' },
-        sourceUrl: ' '.repeat(3),
-        tokenError: '',
-      })
-    ).toEqual({ kind: 'create' });
-  });
 });
diff --git a/frontend/src/__tests__/mocks/apiFixtures.ts b/frontend/src/__tests__/mocks/apiFixtures.ts
index 2d1c6651..e98560c7 100644
--- a/frontend/src/__tests__/mocks/apiFixtures.ts
+++ b/frontend/src/__tests__/mocks/apiFixtures.ts
@@ -102,6 +102,13 @@ export function buildStructuredErrorResponse(overrides: StructuredErrorOverrides
 }
 
 /** Prefer request selectors so validate does not invent an `article` items selector. */
+export function pageUrlFrom(body: unknown): string | undefined {
+  if (typeof body === 'object' && body && 'url' in body && typeof body.url === 'string' && body.url.trim()) {
+    return body.url;
+  }
+  return undefined;
+}
+
 export function selectorsFromValidateRequest(body: unknown): unknown {
   if (typeof body === 'object' && body && 'selectors' in body && body.selectors !== undefined) {
     return body.selectors;
@@ -109,7 +116,8 @@ export function selectorsFromValidateRequest(body: unknown): unknown {
   return { items: { selector: 'a[href]', enhance: false } };
 }
 
-export function validateYamlForSelectors(selectors: unknown): string {
+export function validateYamlForSelectors(selectors: unknown, url?: string): string {
+  const channel = url ? `channel:\n  url: ${url}\n` : '';
   if (
     typeof selectors === 'object' &&
     selectors &&
@@ -121,9 +129,9 @@ export function validateYamlForSelectors(selectors: unknown): string {
   ) {
     const enhance =
       'enhance' in selectors.items && selectors.items.enhance === true ? '\n    enhance: true' : '';
-    return `selectors:\n  items:\n    selector: ${selectors.items.selector}${enhance}\n`;
+    return `${channel}selectors:\n  items:\n    selector: ${selectors.items.selector}${enhance}\n`;
   }
-  return 'selectors: {}\n';
+  return `${channel}selectors: {}\n`;
 }
 
 export function validateSuccessBody(selectors?: unknown, yaml?: string) {
diff --git a/frontend/src/__tests__/mocks/server.ts b/frontend/src/__tests__/mocks/server.ts
index 9b00694e..4c5bc11d 100644
--- a/frontend/src/__tests__/mocks/server.ts
+++ b/frontend/src/__tests__/mocks/server.ts
@@ -3,6 +3,7 @@ import { http, HttpResponse } from 'msw';
 import {
   emptyCatalog,
   metadataBody,
+  pageUrlFrom,
   selectorsFromValidateRequest,
   studioPreviewSuccessBody,
   suggestSuccessBody,
@@ -19,8 +20,10 @@ export const server = setupServer(
     return HttpResponse.json(emptyCatalog);
   }),
   http.post('/api/v1/feeds/validate', async ({ request }) => {
-    const selectors = selectorsFromValidateRequest(await request.json());
-    return HttpResponse.json(validateSuccessBody(selectors, validateYamlForSelectors(selectors)));
+    const body = await request.json();
+    const selectors = selectorsFromValidateRequest(body);
+    const yaml = validateYamlForSelectors(selectors, pageUrlFrom(body));
+    return HttpResponse.json(validateSuccessBody(selectors, yaml));
   }),
   http.post('/api/v1/feeds/preview', () => {
     return HttpResponse.json(studioPreviewSuccessBody([]));
diff --git a/frontend/src/__tests__/useFeedFlow.test.ts b/frontend/src/__tests__/useFeedFlow.test.ts
index ad1edf29..b9e35a78 100644
--- a/frontend/src/__tests__/useFeedFlow.test.ts
+++ b/frontend/src/__tests__/useFeedFlow.test.ts
@@ -42,7 +42,6 @@ describe('useFeedFlow', () => {
     token: undefined,
     isLoading: false,
     feedCreationEnabled: true,
-    studioEnabled: true,
     mayCreate: () => 'proceed',
     saveToken: mockSaveToken,
     clearToken: mockClearToken,
@@ -318,49 +317,4 @@ describe('useFeedFlow', () => {
     rerender({ createEntryKey: 1, route: { kind: 'create' } });
     expect(result.current.tokenDraft).toBe('');
   });
-
-  it('replaces a stale refine route with the matching result', async () => {
-    fetchMock
-      .mockResolvedValueOnce(Response.json({ success: true, data: { feed: mockFeed } }))
-      .mockResolvedValueOnce(Response.json({ items: [] }));
-
-    const { result, rerender } = renderHook((properties: FeedFlowDependencies) => useFeedFlow(properties), {
-      initialProps: feedFlowProperties({ token: 'token-1' }),
-    });
-
-    act(() => {
-      result.current.onFeedFieldChange('url', 'https://example.com/articles');
-    });
-    await act(async () => {
-      await result.current.onFeedSubmit({ preventDefault: vi.fn() } as any);
-    });
-
-    mockNavigate.mockClear();
-    rerender(feedFlowProperties({ token: 'token-1', route: { kind: 'refine' } }));
-
-    await waitFor(() => {
-      expect(mockNavigate).toHaveBeenCalledWith(
-        { kind: 'result', feedToken: 'feed-token-1' },
-        { replace: true }
-      );
-    });
-  });
-
-  it('keeps extraction-empty refine when no result exists', async () => {
-    const { result, rerender } = renderHook((properties: FeedFlowDependencies) => useFeedFlow(properties), {
-      initialProps: feedFlowProperties({ token: 'token-1' }),
-    });
-
-    act(() => {
-      result.current.onFeedFieldChange('url', 'https://example.com/articles');
-    });
-    mockNavigate.mockClear();
-    rerender(feedFlowProperties({ token: 'token-1', route: { kind: 'refine' } }));
-
-    await act(async () => {
-      await Promise.resolve();
-    });
-    expect(mockNavigate).not.toHaveBeenCalled();
-    expect(result.current.viewModel.kind).toBe('refine');
-  });
 });
diff --git a/frontend/src/__tests__/useStudio.test.ts b/frontend/src/__tests__/useStudio.test.ts
index a37063f8..e0de1cfc 100644
--- a/frontend/src/__tests__/useStudio.test.ts
+++ b/frontend/src/__tests__/useStudio.test.ts
@@ -250,6 +250,7 @@ describe('useStudio', () => {
     expect(fetchPath(validateInput)).toBe('/api/v1/feeds/validate');
     expect(validateInput.headers.get('Authorization')).toBe(`Bearer ${token}`);
     expect(JSON.parse(await validateInput.clone().text())).toEqual({
+      url: pageUrl,
       selectors: { items: { selector: 'a[href]' } },
     });
 
@@ -331,6 +332,14 @@ describe('useStudio', () => {
     });
     expect(result.current.state.draft.itemsSelector).toBe('a[href]');
 
+    await advanceValidate();
+    await advancePreview();
+    expect(callsTo(fetchMock, '/feeds/preview')).toHaveLength(0);
+    expect(result.current.state.live.status).toBe('idle');
+
+    act(() => {
+      result.current.setItemsSelector('article.edited');
+    });
     await advanceValidate();
     expect(callsTo(fetchMock, '/feeds/preview')).toHaveLength(0);
 
@@ -378,6 +387,10 @@ describe('useStudio', () => {
       useStudio({ url: pageUrl, token, validateDelayMs: 0, previewSettleMs: 0 })
     );
 
+    act(() => {
+      result.current.setItemsSelector('article.held');
+    });
+
     await waitFor(() => expect(result.current.state.live.status).toBe('ready'));
     const ready = result.current.state.live;
     if (ready.status !== 'ready') return;
@@ -412,7 +425,7 @@ describe('useStudio', () => {
     mockStudioFetch(fetchMock);
 
     const { result } = renderHook(() =>
-      useStudio({ url: pageUrl, token, live: 'after-edit', validateDelayMs: 0, previewSettleMs: 0 })
+      useStudio({ url: pageUrl, token, validateDelayMs: 0, previewSettleMs: 0 })
     );
 
     await waitFor(() => {
@@ -548,6 +561,10 @@ describe('useStudio', () => {
       useStudio({ url: pageUrl, token, validateDelayMs: 0, previewSettleMs: 0 })
     );
 
+    act(() => {
+      result.current.setItemsSelector('article.imaged');
+    });
+
     await waitFor(() => expect(result.current.state.live.status).toBe('ready'));
     const live = result.current.state.live;
     if (live.status !== 'ready') return;
diff --git a/frontend/src/api/generated/types.gen.ts b/frontend/src/api/generated/types.gen.ts
index 2465bd10..b4fc1ab6 100644
--- a/frontend/src/api/generated/types.gen.ts
+++ b/frontend/src/api/generated/types.gen.ts
@@ -383,6 +383,7 @@ export type SuggestSelectorsResponse = SuggestSelectorsResponses[keyof SuggestSe
 export type ValidateFeedConfigData = {
   body?: {
     selectors?: RefinedSelectorsDocument;
+    url?: string;
     yaml?: string;
   };
   headers: {
diff --git a/frontend/src/api/http/feeds.ts b/frontend/src/api/http/feeds.ts
index 6450ea21..c3426647 100644
--- a/frontend/src/api/http/feeds.ts
+++ b/frontend/src/api/http/feeds.ts
@@ -63,10 +63,11 @@ export function postCreateFeed(
 
 export function postValidateFeed(
   token: string,
+  url: string,
   selectors: RefinedSelectorsDocument,
   signal?: AbortSignal
 ): Promise<HttpEnvelope> {
-  const body: ValidateFeedBody = { selectors };
+  const body: ValidateFeedBody = { selectors, url };
   return jsonWrite(FEED_WRITE_URL.validate, token, body, signal);
 }
 
diff --git a/frontend/src/components/App.tsx b/frontend/src/components/App.tsx
index 75ad5340..5c38706b 100644
--- a/frontend/src/components/App.tsx
+++ b/frontend/src/components/App.tsx
@@ -1,7 +1,6 @@
 import type { JSX } from 'preact';
 import { ResultDisplay } from './ResultDisplay';
 import { CreateFeedPanel, UtilityStrip } from './AppPanels';
-import { ConfigStudio } from './ConfigStudio';
 import { Notice } from './Notice';
 import { COPY } from '../journey/copy';
 import { useSession } from '../session';
@@ -65,7 +64,6 @@ export function App() {
     onRetryCreate,
     onCreateAnother,
     generateFromStudio,
-    onRefine,
     onStudioUrlChange,
     onStudioUrlCleared,
     onRetryPreview,
@@ -77,7 +75,6 @@ export function App() {
     token,
     isLoading: sessionLoading,
     feedCreationEnabled,
-    studioEnabled,
     mayCreate,
     saveToken,
     clearToken,
@@ -127,16 +124,6 @@ export function App() {
         studio={studio}
       />
     );
-  } else if (viewModel.kind === 'refine') {
-    bodyContent = (
-      <ConfigStudio
-        url={sourceUrl}
-        token={token ?? ''}
-        onUrlChange={onStudioUrlChange}
-        onUrlCleared={onStudioUrlCleared}
-        onGenerate={generateFromStudio}
-      />
-    );
   } else {
     bodyContent = (
       <CreateFeedPanel
@@ -147,8 +134,6 @@ export function App() {
         feedFieldErrors={feedFieldErrors}
         submitDisabled={submitDisabled}
         feedCreationEnabled={feedCreationEnabled}
-        studioEnabled={studioEnabled}
-        hasAccessToken={Boolean(token?.trim())}
         catalogEntries={catalogEntries}
         featuredFeeds={featuredFeeds}
         tokenDraft={tokenDraft}
@@ -158,7 +143,6 @@ export function App() {
         onSaveToken={onSaveToken}
         onCancelTokenPrompt={onCancelTokenPrompt}
         onRetryCreate={onRetryCreate}
-        onRefine={onRefine}
       />
     );
   }
diff --git a/frontend/src/components/AppPanels.tsx b/frontend/src/components/AppPanels.tsx
index 130ff096..5e5f73ae 100644
--- a/frontend/src/components/AppPanels.tsx
+++ b/frontend/src/components/AppPanels.tsx
@@ -17,7 +17,7 @@ export interface FeedFieldErrors {
   form: string;
 }
 
-type CreatePanelViewModel = Exclude<AppViewModel, { kind: 'result' } | { kind: 'refine' }>;
+type CreatePanelViewModel = Exclude<AppViewModel, { kind: 'result' }>;
 
 interface CreateFeedPanelProperties {
   focusComposerKey: number;
@@ -27,8 +27,6 @@ interface CreateFeedPanelProperties {
   feedFieldErrors: FeedFieldErrors;
   submitDisabled: boolean;
   feedCreationEnabled: boolean;
-  studioEnabled: boolean;
-  hasAccessToken: boolean;
   catalogEntries: CatalogEntry[];
   featuredFeeds: CatalogEntry[];
   tokenDraft: string;
@@ -38,7 +36,6 @@ interface CreateFeedPanelProperties {
   onSaveToken: () => void;
   onCancelTokenPrompt: () => void;
   onRetryCreate: () => void;
-  onRefine: () => void;
 }
 
 interface UrlEntrySectionProperties {
@@ -356,21 +353,15 @@ interface ActionFeedbackProperties {
   failureMessage: string;
   isCreating: boolean;
   isShowRetryButton: boolean;
-  shouldOfferRefine: boolean;
   onRetryCreate: () => void;
-  onRefine: () => void;
 }
 
 function ActionFeedback({
   failureMessage,
   isCreating,
   isShowRetryButton,
-  shouldOfferRefine,
   onRetryCreate,
-  onRefine,
 }: ActionFeedbackProperties) {
-  const hasActions = isShowRetryButton || shouldOfferRefine;
-
   return (
     <>
       {failureMessage && (
@@ -379,19 +370,10 @@ function ActionFeedback({
           tone="error"
           title={isShowRetryButton ? COPY.createFailedRetryTitle : COPY.createFailedTitle}
           actions={
-            hasActions ? (
-              <>
-                {isShowRetryButton ? (
-                  <button type="button" class="btn btn--primary" onClick={onRetryCreate}>
-                    {COPY.tryAgain}
-                  </button>
-                ) : undefined}
-                {shouldOfferRefine ? (
-                  <button type="button" class="btn btn--quiet btn--linkish" onClick={onRefine}>
-                    {COPY.refineSelectors}
-                  </button>
-                ) : undefined}
-              </>
+            isShowRetryButton ? (
+              <button type="button" class="btn btn--primary" onClick={onRetryCreate}>
+                {COPY.tryAgain}
+              </button>
             ) : undefined
           }
         >
@@ -412,8 +394,6 @@ export function CreateFeedPanel({
   feedFieldErrors,
   submitDisabled,
   feedCreationEnabled,
-  studioEnabled,
-  hasAccessToken,
   catalogEntries,
   featuredFeeds,
   tokenDraft,
@@ -423,7 +403,6 @@ export function CreateFeedPanel({
   onSaveToken,
   onCancelTokenPrompt,
   onRetryCreate,
-  onRefine,
 }: CreateFeedPanelProperties) {
   const urlInputReference = useRef<HTMLInputElement>(null);
   const tokenInputReference = useRef<HTMLInputElement>(null);
@@ -443,11 +422,6 @@ export function CreateFeedPanel({
   const isShowRetryButton = Boolean(
     creationError && creationError.nextAction === 'retry' && creationError.retryAction !== 'none'
   );
-  const shouldOfferRefine =
-    studioEnabled &&
-    hasAccessToken &&
-    viewModel.kind === 'error' &&
-    creationError?.code === 'EXTRACTION_EMPTY';
   const isCreatingFeed = !isTokenPrompt && isSubmitting;
   const tokenCreating = isTokenPrompt && flowCreating;
 
@@ -519,9 +493,7 @@ export function CreateFeedPanel({
           failureMessage={failureMessage}
           isCreating={isCreatingFeed}
           isShowRetryButton={isShowRetryButton}
-          shouldOfferRefine={shouldOfferRefine}
           onRetryCreate={onRetryCreate}
-          onRefine={onRefine}
         />
       </div>
       {isTokenPrompt ? (
diff --git a/frontend/src/components/ConfigStudio.tsx b/frontend/src/components/ConfigStudio.tsx
index 5caaced1..f5dff9ec 100644
--- a/frontend/src/components/ConfigStudio.tsx
+++ b/frontend/src/components/ConfigStudio.tsx
@@ -24,34 +24,28 @@ import type { StudioIssue, StudioSampleItem, StudioSuggestion } from '../studio/
 /** Settle delay before URL edits re-trigger suggest / validate / preview. */
 export const STUDIO_URL_SETTLE_MS = 400;
 
-interface StudioControls {
+interface ConfigStudioProperties {
   readonly url: string;
   readonly token: string;
   readonly onUrlChange: (url: string) => void;
   readonly onUrlCleared: () => void;
   readonly onGenerate: (selectors: RefinedSelectorsDocument) => Promise<void>;
+  /** Create-time meadow shown until the first studio sample replaces it. */
+  readonly fallback?: ComponentChildren;
 }
 
-type ConfigStudioProperties = StudioControls &
-  (
-    | { readonly placement?: 'recovery' }
-    | { readonly placement: 'inline'; readonly fallback: ComponentChildren }
-  );
-
 interface OpenPanel {
   readonly field: StudioFieldId;
   readonly nonce: number;
 }
 
 export function ConfigStudio(properties: ConfigStudioProperties) {
-  const { url, token, onUrlChange, onUrlCleared, onGenerate } = properties;
-  const isInline = properties.placement === 'inline';
+  const { url, token, onUrlChange, onUrlCleared, onGenerate, fallback } = properties;
   const [urlDraft, setUrlDraft] = useState(url);
   const [settledUrl, setSettledUrl] = useState(url);
   const studio = useStudio({
     url: settledUrl,
     token,
-    live: isInline ? 'after-edit' : 'immediate',
   });
   const { state, suggestion } = studio;
   const issues = studioIssues(state);
@@ -59,7 +53,6 @@ export function ConfigStudio(properties: ConfigStudioProperties) {
   const [yamlOpen, setYamlOpen] = useState(false);
   const [copied, setCopied] = useState(false);
   const [showUnmapped, setShowUnmapped] = useState(false);
-  const itemsReference = useRef<HTMLInputElement>(null);
   const copyResetReference = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
   const openField = panel?.field;
   const hiddenIssues = issues.filter((issue) => isHiddenIssue(issue, openField));
@@ -86,11 +79,6 @@ export function ConfigStudio(properties: ConfigStudioProperties) {
     return () => clearTimeout(timer);
   }, [urlDraft, settledUrl, onUrlChange]);
 
-  useEffect(() => {
-    if (isInline) return;
-    itemsReference.current?.focus();
-  }, [isInline]);
-
   useEffect(() => {
     if (!panel) return;
     focusElement('studio-field-selector');
@@ -130,7 +118,8 @@ export function ConfigStudio(properties: ConfigStudioProperties) {
     return true;
   };
 
-  const shouldShowCreateMeadow = isInline && sample === undefined && state.live.status !== 'failed';
+  const shouldShowCreateMeadow =
+    fallback !== undefined && sample === undefined && state.live.status !== 'failed';
   const meadow = shouldShowCreateMeadow ? (
     <>
       {properties.fallback}
@@ -152,6 +141,20 @@ export function ConfigStudio(properties: ConfigStudioProperties) {
 
   const authoring = (
     <div class="layout-rail-reading layout-stack refine-controls">
+      <label class="field-block" htmlFor="studio-url">
+        <span class="ui-eyebrow">{COPY.urlLabel}</span>
+        <input
+          id="studio-url"
+          class="input input--mono input--lg"
+          type="url"
+          value={urlDraft}
+          spellcheck={false}
+          autoComplete="url"
+          onInput={(event) => setUrlDraft(inputValue(event))}
+          onBlur={onUrlBlur}
+        />
+      </label>
+
       {state.phase === 'failed' ? (
         <Notice title={COPY.createFailedTitle} tone="error">
           {state.message.trim() && state.message !== COPY.createFailedTitle ? (
@@ -166,8 +169,6 @@ export function ConfigStudio(properties: ConfigStudioProperties) {
           id="studio-items-selector"
           class="input input--mono input--lg"
           value={state.draft.itemsSelector}
-          autoFocus={!isInline}
-          ref={itemsReference}
           spellcheck={false}
           onInput={(event) => studio.setItemsSelector(inputValue(event))}
         />
@@ -237,21 +238,7 @@ export function ConfigStudio(properties: ConfigStudioProperties) {
   );
 
   const support = (
-    <div class="layout-rail-reading layout-stack layout-stack--tight refine-support">
-      <label class="field-block" htmlFor="studio-url">
-        <span class="ui-eyebrow">{COPY.urlLabel}</span>
-        <input
-          id="studio-url"
-          class="input input--mono"
-          type="url"
-          value={urlDraft}
-          spellcheck={false}
-          autoComplete="url"
-          onInput={(event) => setUrlDraft(inputValue(event))}
-          onBlur={onUrlBlur}
-        />
-      </label>
-
+    <div class="layout-rail-reading layout-stack layout-stack--tight layout-section-divided refine-support">
       {nativeFeedUrl ? (
         <Notice title={COPY.nativeFeedTitle}>
           <a class="input--mono" href={nativeFeedUrl} target="_blank" rel="noopener noreferrer">
@@ -280,39 +267,19 @@ export function ConfigStudio(properties: ConfigStudioProperties) {
             >
               {copied ? COPY.copied : COPY.copy}
             </button>
-            <p class="field-help">{COPY.yamlFragmentCaption}</p>
+            <p class="field-help">{COPY.yamlCaption}</p>
           </>
         ) : undefined}
       </div>
     </div>
   );
 
-  if (isInline) {
-    return (
-      <div class="layout-stack" aria-busy={isBusy}>
-        {authoring}
-        {meadow}
-        {support}
-      </div>
-    );
-  }
-
   return (
-    <section
-      class="result-shell layout-stack"
-      data-state="refine"
-      aria-labelledby="refine-title"
-      aria-busy={isBusy}
-    >
-      <header class="layout-rail-reading layout-stack layout-stack--tight">
-        <h1 id="refine-title" class="ui-display-title">
-          {COPY.refineSelectors}
-        </h1>
-      </header>
+    <div class="layout-stack" aria-busy={isBusy}>
       {authoring}
       {meadow}
       {support}
-    </section>
+    </div>
   );
 }
 
@@ -337,8 +304,8 @@ function CandidateChoices({
 
   return (
     <div class="refine-candidates" role="group" aria-label={COPY.selectorChoices}>
+      <p class="ui-eyebrow">{COPY.selectorChoices}</p>
       <SelectorChips
-        heading={COPY.itemsSelector}
         label={COPY.choicesFor(COPY.itemsSelector)}
         current={draft.itemsSelector}
         parts={items}
@@ -376,7 +343,7 @@ function SelectorChips({
   parts,
   onToggle,
 }: {
-  readonly heading: string;
+  readonly heading?: string;
   readonly label: string;
   readonly current: string;
   readonly parts: readonly string[];
@@ -386,7 +353,7 @@ function SelectorChips({
 
   return (
     <div class="refine-candidates__bucket" role="group" aria-label={label}>
-      <p class="ui-eyebrow">{heading}</p>
+      {heading ? <p class="ui-eyebrow">{heading}</p> : undefined}
       <ul class="refine-candidates__chips">
         {parts.map((selector) => {
           const pressed = hasEverySelectorPart(current, selector);
diff --git a/frontend/src/components/ResultDisplay.tsx b/frontend/src/components/ResultDisplay.tsx
index 42af606f..fa9ac7ee 100644
--- a/frontend/src/components/ResultDisplay.tsx
+++ b/frontend/src/components/ResultDisplay.tsx
@@ -142,7 +142,6 @@ export function ResultDisplay({
             {...(refineOpen ? {} : { hidden: true as const, 'aria-hidden': true as const })}
           >
             <ConfigStudio
-              placement="inline"
               url={studio.url}
               token={studio.token}
               onUrlChange={studio.onUrlChange}
diff --git a/frontend/src/feed/decideJourney.ts b/frontend/src/feed/decideJourney.ts
index 9b63eefe..5c2fedff 100644
--- a/frontend/src/feed/decideJourney.ts
+++ b/frontend/src/feed/decideJourney.ts
@@ -23,8 +23,7 @@ export type AppViewModel =
       message: string;
       error?: FeedCreationError;
       errorKind?: FeedCreationError['kind'];
-    }
-  | { kind: 'refine' };
+    };
 
 /**
  * Pure projection of journey kind from Feed Flow state.
@@ -36,7 +35,6 @@ export function decideJourney({
   feedFieldErrors,
   isCreating,
   route,
-  sourceUrl,
   tokenError,
   result,
 }: {
@@ -44,14 +42,9 @@ export function decideJourney({
   feedFieldErrors: { url: string; form: string };
   isCreating: boolean;
   route: AppRoute;
-  sourceUrl: string;
   tokenError: string;
   result?: CreatedFeedResult;
 }): AppViewModel {
-  if (route.kind === 'refine') {
-    return sourceUrl.trim() ? { kind: 'refine' } : { kind: 'create' };
-  }
-
   if (route.kind === 'result' && result && result.feed.feed_token === route.feedToken) {
     return {
       kind: 'result',
diff --git a/frontend/src/feed/useFeedFlow.ts b/frontend/src/feed/useFeedFlow.ts
index 14023916..f4f16d22 100644
--- a/frontend/src/feed/useFeedFlow.ts
+++ b/frontend/src/feed/useFeedFlow.ts
@@ -20,7 +20,6 @@ export interface FeedFlowDependencies {
   token: string | undefined;
   isLoading: boolean;
   feedCreationEnabled: boolean;
-  studioEnabled: boolean;
   mayCreate: (accessToken?: string) => MayCreateResult;
   saveToken: (token: string) => Promise<void>;
   clearToken: () => void;
@@ -36,7 +35,6 @@ export function useFeedFlow({
   token,
   isLoading,
   feedCreationEnabled,
-  studioEnabled,
   mayCreate,
   saveToken,
   clearToken,
@@ -206,23 +204,6 @@ export function useFeedFlow({
     navigate({ kind: 'create' }, { replace: true });
   }, [navigate, result, route]);
 
-  // Recover refine onto the result that already owns refinement, or create when recovery is unavailable.
-  useEffect(() => {
-    if (route.kind !== 'refine') return;
-    if (!studioEnabled || !token?.trim()) {
-      navigate({ kind: 'create' }, { replace: true });
-      return;
-    }
-    if (result) {
-      navigate({ kind: 'result', feedToken: result.feed.feed_token }, { replace: true });
-      return;
-    }
-    if (inMemorySourceUrl(feedFormData.url, undefined)) return;
-
-    // Do not carry a prefill URL — that would re-trigger auto-submit.
-    navigate({ kind: 'create' }, { replace: true });
-  }, [feedFormData.url, navigate, result, route, studioEnabled, token]);
-
   useEffect(() => {
     const previousKind = previousRouteKindReference.current;
     const previousCreateEntryKey = previousCreateEntryKeyReference.current;
@@ -287,7 +268,6 @@ export function useFeedFlow({
     feedFieldErrors,
     isCreating,
     route,
-    sourceUrl,
     tokenError,
     result,
   });
@@ -327,10 +307,6 @@ export function useFeedFlow({
       setFocusCreateComposerKey((current) => current + 1);
       navigate({ kind: 'create', prefillUrl: feedFormData.url || undefined });
     },
-    onRefine: () => {
-      if (!studioEnabled || !token?.trim() || result) return;
-      navigate({ kind: 'refine' });
-    },
     onStudioUrlChange: (nextUrl: string) => {
       onFeedFieldChange('url', nextUrl);
     },
diff --git a/frontend/src/journey/copy.ts b/frontend/src/journey/copy.ts
index fe3cba21..faa0ddfb 100644
--- a/frontend/src/journey/copy.ts
+++ b/frontend/src/journey/copy.ts
@@ -1,4 +1,4 @@
-/** Sole UI copy owner for create / token / result / refine journey states. */
+/** Sole UI copy owner for create / token / result journey states. */
 export const COPY = {
   creating: 'Creating feed',
   previewChecking: 'Checking preview',
@@ -77,7 +77,7 @@ export const COPY = {
   removeSelector: (selector: string) => `Remove ${selector}`,
   saveAndGenerate: 'Save and generate feed',
   viewAsYaml: 'View as YAML',
-  yamlFragmentCaption: 'Selectors fragment — not a feeds.yml config',
+  yamlCaption: 'Channel URL and selectors for this page',
   previewFetchedCaption: 'Based on the page already fetched for this URL',
   nativeFeedTitle: 'This site already publishes a feed.',
   fieldTitle: 'Title',
diff --git a/frontend/src/routes/appRoute.ts b/frontend/src/routes/appRoute.ts
index 6d4daf8a..27ec38db 100644
--- a/frontend/src/routes/appRoute.ts
+++ b/frontend/src/routes/appRoute.ts
@@ -12,9 +12,6 @@ export type AppRoute =
   | {
       kind: 'result';
       feedToken: string;
-    }
-  | {
-      kind: 'refine';
     };
 
 interface RouteNavigationOptions {
@@ -30,7 +27,6 @@ interface RouteLocationLike {
 const ROUTE_PATHS = {
   create: '/create',
   token: '/token',
-  refine: '/refine',
   resultPrefix: '/result/',
 } as const;
 
@@ -47,10 +43,6 @@ export function readAppRoute(locationLike: RouteLocationLike = getCurrentLocatio
     return prefillUrl ? { kind: 'token', prefillUrl } : { kind: 'token' };
   }
 
-  if (pathname === ROUTE_PATHS.refine) {
-    return { kind: 'refine' };
-  }
-
   if (pathname.startsWith(ROUTE_PATHS.resultPrefix)) {
     const feedToken = pathname.slice(ROUTE_PATHS.resultPrefix.length);
     if (feedToken) return { kind: 'result', feedToken };
@@ -80,12 +72,6 @@ export function buildAppRouteHref(route: AppRoute, baseHref = getCurrentHref()):
     return url.href;
   }
 
-  if (route.kind === 'refine') {
-    url.hash = ROUTE_PATHS.refine;
-    url.search = '';
-    return url.href;
-  }
-
   url.hash = `${ROUTE_PATHS.resultPrefix}${route.feedToken}`;
   url.search = '';
   return url.href;
diff --git a/frontend/src/studio/studioService.ts b/frontend/src/studio/studioService.ts
index d44edfb1..8289ed31 100644
--- a/frontend/src/studio/studioService.ts
+++ b/frontend/src/studio/studioService.ts
@@ -94,10 +94,11 @@ const STUDIO_ISSUE_CODES = listedIssueCodes([
 
 export function validateStudioSelectors(
   token: string,
+  url: string,
   draft: StudioDraft,
   signal?: AbortSignal
 ): Promise<StudioValidationOutcome> {
-  return validateStudio(token, selectorsFromDraft(draft), signal);
+  return validateStudio(token, url, selectorsFromDraft(draft), signal);
 }
 
 export async function previewStudioFeed(
@@ -122,10 +123,11 @@ export async function suggestStudioSelectors(
 
 async function validateStudio(
   token: string,
+  url: string,
   selectors: RefinedSelectorsDocument,
   signal?: AbortSignal
 ): Promise<StudioValidationOutcome> {
-  return parseValidation(await studioData(await postValidateFeed(token, selectors, signal)));
+  return parseValidation(await studioData(await postValidateFeed(token, url, selectors, signal)));
 }
 
 async function studioData(envelope: HttpEnvelope): Promise<unknown> {
diff --git a/frontend/src/studio/useStudio.ts b/frontend/src/studio/useStudio.ts
index 4338471c..8964a947 100644
--- a/frontend/src/studio/useStudio.ts
+++ b/frontend/src/studio/useStudio.ts
@@ -51,8 +51,6 @@ interface UseStudioOptions {
   readonly token: string;
   readonly validateDelayMs?: number;
   readonly previewSettleMs?: number;
-  /** `after-edit` skips mount-time live preview so a result meadow can stay single. */
-  readonly live?: 'immediate' | 'after-edit';
 }
 
 export function useStudio({
@@ -60,7 +58,6 @@ export function useStudio({
   token,
   validateDelayMs = STUDIO_VALIDATE_DELAY_MS,
   previewSettleMs = STUDIO_PREVIEW_SETTLE_MS,
-  live = 'immediate',
 }: UseStudioOptions) {
   const [state, setState] = useState<StudioState>({
     phase: 'editing',
@@ -98,7 +95,7 @@ export function useStudio({
       clearTimeout(timer);
       controller.abort();
     };
-  }, [documentRevision, live, token, url, validateDelayMs]);
+  }, [documentRevision, token, url, validateDelayMs]);
 
   useEffect(() => {
     const requestId = ++suggestRequestReference.current;
@@ -108,7 +105,7 @@ export function useStudio({
     return () => {
       controller.abort();
     };
-  }, [live, url, token]);
+  }, [url, token]);
 
   useEffect(() => {
     return () => {
@@ -138,7 +135,7 @@ export function useStudio({
     }));
 
     try {
-      const outcome = await validateStudioSelectors(token, sentDraft, signal);
+      const outcome = await validateStudioSelectors(token, url, sentDraft, signal);
       if (signal.aborted || requestIdReference.current !== requestId) return;
       commitValidation(outcome, sentDraft, revision);
     } catch (error) {
@@ -175,7 +172,7 @@ export function useStudio({
       validated: true,
       live: previous.live,
     }));
-    if (live === 'after-edit' && revision === 0 && url === initialUrlReference.current) return;
+    if (revision === 0 && url === initialUrlReference.current) return;
     schedulePreview();
   }
 
diff --git a/public/openapi.yaml b/public/openapi.yaml
index 8cf6cc8b..1915726b 100644
--- a/public/openapi.yaml
+++ b/public/openapi.yaml
@@ -693,6 +693,8 @@ paths:
               properties:
                 selectors:
                   "$ref": "#/components/schemas/RefinedSelectorsDocument"
+                url:
+                  type: string
                 yaml:
                   type: string
               type: object
diff --git a/spec/html2rss/web/api/v1_spec.rb b/spec/html2rss/web/api/v1_spec.rb
index 55f5bad0..fcdd4e3f 100644
--- a/spec/html2rss/web/api/v1_spec.rb
+++ b/spec/html2rss/web/api/v1_spec.rb
@@ -889,7 +889,10 @@ def post_validate(payload)
     let(:perform_request) do
       lambda {
         header 'Content-Type', 'application/json'
-        post '/api/v1/feeds/validate', { selectors: { items: { selector: 'article' } } }.to_json
+        post '/api/v1/feeds/validate', {
+          selectors: { items: { selector: 'article' } },
+          url: 'https://example.com/articles'
+        }.to_json
       }
     end
 
@@ -909,7 +912,7 @@ def post_validate(payload)
         url: { selector: 'a', extractor: 'href' },
         published_at: { selector: 'time', extractor: 'text' }
       }
-      post_validate(selectors:)
+      post_validate({ selectors:, url: 'https://example.com/articles' })
 
       json = expect_success_response(last_response)
       expect(json.dig('data', 'report', 'success')).to be(true)
@@ -918,6 +921,22 @@ def post_validate(payload)
       expect(json.dig('data', 'selectors', 'url', 'extractor')).to eq('href')
     end
 
+    it 'exports the page url beside the selectors' do
+      post_validate({ selectors: { items: { selector: 'article' } }, url: 'https://example.com/articles' })
+
+      json = expect_success_response(last_response)
+      exported = YAML.safe_load(json.dig('data', 'yaml'))
+      expect(exported.dig('channel', 'url')).to eq(Html2rss::Web::UrlValidator.canonical_url('https://example.com/articles'))
+      expect(exported.dig('selectors', 'items', 'selector')).to eq('article')
+    end
+
+    it 'rejects an unusable page url' do
+      post_validate({ selectors: { items: { selector: 'article' } }, url: 'not a url' })
+
+      expect(last_response.status).to eq(400)
+      expect(JSON.parse(last_response.body).dig('error', 'message')).to eq('Invalid URL format')
+    end
+
     it 'returns a parse issue for unparseable yaml' do
       post_validate(yaml: "selectors: [\n")
 

From 3baf696eca022416f1216186fda55719020c7f10 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Mon, 21 Sep 2026 16:16:14 +0200
Subject: [PATCH 074/108] fix(studio): keep result refine on the created
 listing

Hide the refine URL field so token holders change listings via Create another feed, and stop validate from treating transport url as a config key. Frame View as YAML as a notice card and load preview images without a CORS handshake.
---
 AGENTS.md                                     |  2 +-
 CONTEXT.md                                    |  2 +-
 app/web/api/v1/validate_config.rb             | 10 +++
 docs/design-system.md                         |  2 +-
 docs/personas.md                              |  2 +-
 frontend/e2e/smoke.spec.ts                    | 49 +------------
 frontend/src/__tests__/App.contract.test.tsx  |  1 +
 frontend/src/__tests__/ConfigStudio.test.tsx  | 70 ++++---------------
 frontend/src/__tests__/ResultDisplay.test.tsx |  6 +-
 frontend/src/__tests__/appRoute.test.ts       | 10 +++
 frontend/src/components/App.tsx               |  4 --
 frontend/src/components/ConfigStudio.tsx      | 66 ++---------------
 frontend/src/components/PreviewItem.tsx       |  1 -
 frontend/src/components/ResultDisplay.tsx     |  4 --
 frontend/src/feed/useFeedFlow.ts              |  9 ---
 frontend/src/routes/appRoute.ts               |  7 +-
 16 files changed, 51 insertions(+), 194 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 2431acd5..5d58c6fc 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -87,7 +87,7 @@ Token-holder refinement of the selectors subtree, then generate via create.
 | Disabled response | `403` when the flag is off                                                                                                            |
 | Auth              | Access token required on validate, preview, suggest, and create                                                                       |
 | Live fetch        | Preview and suggest also need `AUTO_SOURCE_ENABLED`                                                                                   |
-| Frontend          | Successful results refine inline on `#/result/:token`. There is no `#/refine` route. Empty URL recovers onto remounted `#/create` |
+| Frontend          | Successful results refine inline on `#/result/:token`. There is no `#/refine` route. |
 | Contract SSOT     | Request specs under `spec/html2rss/web/api/v1_spec.rb` and generated `public/openapi.yaml`                                            |
 
 After handler or envelope changes: `make openapi` and `make ci-ready`.
diff --git a/CONTEXT.md b/CONTEXT.md
index 0a303802..e4422583 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -29,7 +29,7 @@ On create, `findCatalogEntries` matches the typed query against the catalog (URL
 Visiting create (including hashbang `#!/…` → `#/…`) bumps `createEntryKey` so the create surface remounts. Remount alone does not auto-submit; auto-submit requires `prefillUrl`.
 
 ### Config Studio
-Selector refinement for a token holder when studio is enabled. On a successful result, refinement is available on demand behind demoted **Refine selectors** on `#/result/:token` (collapsed by default; one meadow; live studio output replaces the result preview after an edit). The page URL leads the controls. The visual builder and YAML are one document: validate exports `channel.url` plus selectors. Only `studioService` unwraps the studio envelope and maps ranked `candidates` (items / title / link / published) into domain suggestion buckets. Candidates never auto-apply. Chips add or remove selector parts on the authored comma-joined string; suggest does not write that string, and chips do not change Enhance. Field extractors remain fixed by the draft mapper. Save posts refined selectors through Creation IO and stays on the result view.
+Selector refinement for a token holder when studio is enabled. On a successful result, refinement is available on demand behind demoted **Refine selectors** on `#/result/:token` (collapsed by default; one meadow; live studio output replaces the result preview after an edit). The listing URL stays the created feed’s page; **Create another feed** starts a new listing. The visual builder and YAML are one document: validate exports `channel.url` plus selectors. Only `studioService` unwraps the studio envelope and maps ranked `candidates` (items / title / link / published) into domain suggestion buckets. Candidates never auto-apply. Chips add or remove selector parts on the authored comma-joined string; suggest does not write that string, and chips do not change Enhance. Field extractors remain fixed by the draft mapper. Save posts refined selectors through Creation IO and stays on the result view.
 
 ### Refined Selectors
 The allowlisted `selectors` document a token holder may attach on feed creation. Signed into the feed token and resolved on later serves. Not a full config: channel, headers, and strategy stay denied.
diff --git a/app/web/api/v1/validate_config.rb b/app/web/api/v1/validate_config.rb
index 5c3dc38c..da30de40 100644
--- a/app/web/api/v1/validate_config.rb
+++ b/app/web/api/v1/validate_config.rb
@@ -31,12 +31,22 @@ def call(request)
             # @param url [String, nil]
             # @return [Array(Html2rss::Config::ValidationReport, Hash, nil)]
             def assess(body, url)
+              reject_denied_body_keys!(body)
               return assess_yaml(body['yaml'], url) if body.key?('yaml') && !body['yaml'].nil?
               raise BadRequestError, 'yaml or selectors is required' unless body.key?('selectors')
 
               assess_fragment({ selectors: body['selectors'] }, url)
             end
 
+            # Transport keys (`url`, `selectors`, `yaml`) stay; denied config roots do not.
+            #
+            # @param body [Hash]
+            # @return [void]
+            def reject_denied_body_keys!(body)
+              denied = body.each_key.map { |key| key.to_s.to_sym }.find { RefinedSelectors::DENIED_KEYS.include?(it) }
+              raise BadRequestError, "#{denied} is not allowed" if denied
+            end
+
             # @param yaml [Object]
             # @param url [String, nil]
             # @return [Array(Html2rss::Config::ValidationReport, Hash, nil)]
diff --git a/docs/design-system.md b/docs/design-system.md
index 47a16d2c..656b6894 100644
--- a/docs/design-system.md
+++ b/docs/design-system.md
@@ -40,7 +40,7 @@ If a page looks like it came from a different product, the change is wrong even
 
 - **Create:** URL field is the task. Visiting `#/create` or `#!/create` remounts create; hashbang aliases canonicalize to `#/create`. Bare create does not auto-submit. When the typed query finds catalog entries (URL equivalence or text substring), show matching feeds as a subordinate list under the field — never a second primary task or in-app catalog browser. On an empty Create URL, up to three Feed Directory starters may appear as subordinate chrome (lean: `.ui-eyebrow` + list + demoted `utility-link` escape under the list when creation is enabled; Notice when creation is disabled). Escape and utility-strip share **Browse Feed Directory (N)** (`catalogEntries.length`); hide starters and the under-list escape while typing, when find has hits, or while creating.
 - **Token gate:** a native `<dialog>` over the still-mounted, inert URL task (one interactive task). Auth copy is in-field (`tokenError`); ActionFeedback stays on create. Access Token persists until Logout with no storage UI.
-- **Result:** primary CTA is **Copy feed URL**, and it takes initial focus. Open feed / JSON / feed-reader are demoted secondary actions and stay available while preview loads. Preview is one meadow and non-blocking confirmation only. Guest results stay compact: at most 5 items, no images, no selector controls. An authenticated, studio-enabled result keeps that same frame: a demoted **Refine selectors** action in `ui-actions` (collapsed by default). Opening it mounts selector controls **above** the meadow; closing it returns to the static meadow without discarding the in-memory draft. The page URL leads those controls, then the items selector, ranked **Selector choices**, Enhance, and **Save and generate feed** as the only `btn--primary` inside the panel. Studio validate/preview/suggest do not run until the panel opens, and the first live preview waits for an edit so the create-time meadow stays single. Selector edits keep the previous meadow visible and mark it loading until live studio output replaces it. They do not add a second list, and they do not return to the create-time meadow once a studio sample exists. Until that sample exists, including while the first studio preview loads, the result keeps its create-time meadow. The studio meadow is captioned as the page already fetched for this URL. Member previews may show up to 10 items and safe HTTP(S) images. A native-feed Notice and **View as YAML** sit below the meadow. View as YAML is read-only `channel.url` plus selectors for this page. Changing the URL re-suggests and re-previews without leaving the result or running catalog find; an empty URL recovers onto remounted `#/create`. There is no `#/refine` route. Ranked candidates (items, title, link, published) are wrapping pills on the authored selector: `--radius-pill`, `--space-2`/`--space-3` padding, a transparent outline when idle, and `--surface-elevated` with `--border-strong` when pressed. A pill and its list item use `min-width: 0` and `max-width: 100%`; the pill uses `overflow-wrap: anywhere`. A pill adds or removes its selector parts in the comma-joined draft string; suggest does not write that string. Pills do not change Enhance. Empty buckets stay hidden. Wire is the typed closed selectors document (no strip/trim/affix cleanup UI). Fix a field opens one selector panel **in the stack** for Title, Link, or Published date. Save-failure Notices use wire `Decision#message`. When studio is disabled or the caller has no token, Refine stays hidden. Focus stays on Copy whether Refine is open or closed.
+- **Result:** primary CTA is **Copy feed URL**, and it takes initial focus. Open feed / JSON / feed-reader are demoted secondary actions and stay available while preview loads. Preview is one meadow and non-blocking confirmation only. Guest results stay compact: at most 5 items, no images, no selector controls. An authenticated, studio-enabled result keeps that same frame: a demoted **Refine selectors** action in `ui-actions` (collapsed by default). Opening it mounts selector controls **above** the meadow; closing it returns to the static meadow without discarding the in-memory draft. The items selector, ranked **Selector choices**, Enhance, and **Save and generate feed** as the only `btn--primary` inside the panel. Studio validate/preview/suggest do not run until the panel opens, and the first live preview waits for an edit so the create-time meadow stays single. Selector edits keep the previous meadow visible and mark it loading until live studio output replaces it. They do not add a second list, and they do not return to the create-time meadow once a studio sample exists. Until that sample exists, including while the first studio preview loads, the result keeps its create-time meadow. The studio meadow is captioned as the page already fetched for this URL. Member previews may show up to 10 items and safe HTTP(S) images. A native-feed Notice and **View as YAML** sit below the meadow. View as YAML is read-only `channel.url` plus selectors for this page, framed as `.ui-card.ui-card--notice` (not `.input`, whose pill radius is for controls). A different listing is **Create another feed**. There is no `#/refine` route. Ranked candidates (items, title, link, published) are wrapping pills on the authored selector: `--radius-pill`, `--space-2`/`--space-3` padding, a transparent outline when idle, and `--surface-elevated` with `--border-strong` when pressed. A pill and its list item use `min-width: 0` and `max-width: 100%`; the pill uses `overflow-wrap: anywhere`. A pill adds or removes its selector parts in the comma-joined draft string; suggest does not write that string. Pills do not change Enhance. Empty buckets stay hidden. Wire is the typed closed selectors document (no strip/trim/affix cleanup UI). Fix a field opens one selector panel **in the stack** for Title, Link, or Published date. Save-failure Notices use wire `Decision#message`. When studio is disabled or the caller has no token, Refine stays hidden. Focus stays on Copy whether Refine is open or closed.
 - **Empty extraction:** a create error. **Try again** when the decision is retryable. Selector refinement stays on a successful result.
 - **Unmatched result:** `#/result/:token` is valid only with a matching in-memory result. Missing or mismatched tokens recover onto remounted `#/create` (no API rehydrate, no failure chrome, no durable shareable result page).
 - **Status eyebrow:** one vocabulary (`Feed ready`) on the result header; preview progress lives in the preview section.
diff --git a/docs/personas.md b/docs/personas.md
index a7a79210..0343eae0 100644
--- a/docs/personas.md
+++ b/docs/personas.md
@@ -20,7 +20,7 @@ Bookmarklet is a **Sam on-ramp**, not a fifth persona.
 - **Job:** Paste a listing URL, get a feed URL, subscribe in a reader.
 - **Owning surface:** html2rss-web SPA.
 - **Golden path:** Create → token (if needed) → Result → **Copy feed URL**.
-- **Recovery only:** wrong list, missing Title/Link/Published, or a wrong listing URL stay on Result for a token holder when studio is enabled, behind demoted **Refine selectors** (collapsed by default). It is not an authoring product. Empty extraction stays a create error.
+- **Recovery only:** wrong list or missing Title/Link/Published stay on Result for a token holder when studio is enabled, behind demoted **Refine selectors** (collapsed by default). A different listing is **Create another feed**. It is not an authoring product. Empty extraction stays a create error.
 - **Non-goal:** Learning YAML, MCP, or directory contribution through the SPA.
 
 ## Alex — operator
diff --git a/frontend/e2e/smoke.spec.ts b/frontend/e2e/smoke.spec.ts
index 13ea31a1..d67c7674 100644
--- a/frontend/e2e/smoke.spec.ts
+++ b/frontend/e2e/smoke.spec.ts
@@ -22,7 +22,6 @@ const API_STUDIO_PREVIEW = /\/api\/v1\/feeds\/preview\/?$/;
 const API_JSON_PREVIEW = /\/api\/v1\/feeds\/generated-token\.json$/;
 
 const EXAMPLE_URL = 'https://example.com/articles';
-const BLOG_URL = 'https://example.com/blog';
 
 async function fulfillJson(
   page: Page,
@@ -245,6 +244,8 @@ test.describe('frontend smoke', () => {
 
     const items = page.getByLabel(COPY.itemsSelector, { exact: true });
     await expect(items).toBeVisible();
+    await expect(page.getByLabel(COPY.urlLabel, { exact: true })).toHaveCount(0);
+    await expect(page.getByRole('button', { name: COPY.createAnother })).toBeVisible();
     await expect.poll(() => validateRequests.length, { timeout: 5000 }).toBeGreaterThan(0);
     await expect(page.getByRole('group', { name: COPY.selectorChoices, exact: true })).toBeVisible();
     const itemsChoices = page.getByRole('group', {
@@ -284,52 +285,6 @@ test.describe('frontend smoke', () => {
     await expect(page.locator('.result-shell')).toHaveAttribute('data-state', 'result');
   });
 
-  test('re-suggests and re-previews after result URL edit then remounts create on empty blur', async ({
-    page,
-  }) => {
-    const suggestRequests: Request[] = [];
-    const previewRequests: Request[] = [];
-    collectPosts(page, API_SUGGEST, suggestRequests);
-    collectPosts(page, API_STUDIO_PREVIEW, previewRequests);
-
-    await createReadyResult(page);
-    await expect(page).toHaveURL(/\/#\/result\/generated-token$/);
-    await expect(page.locator('.ui-item-list')).toHaveCount(0);
-    expect(suggestRequests).toHaveLength(0);
-    expect(previewRequests).toHaveLength(0);
-
-    await page.getByRole('button', { name: COPY.refineSelectors }).click();
-    await expect(page.getByLabel(COPY.itemsSelector, { exact: true })).toBeVisible();
-    await expect.poll(() => suggestRequests.length, { timeout: 5000 }).toBeGreaterThan(0);
-
-    const suggestBeforeEdit = suggestRequests.length;
-    const previewBeforeEdit = previewRequests.length;
-
-    const urlField = page.getByRole('textbox', { name: COPY.urlLabel, exact: true });
-    await urlField.fill(BLOG_URL);
-    await expect.poll(() => suggestRequests.length, { timeout: 5000 }).toBeGreaterThan(suggestBeforeEdit);
-    await expect.poll(() => previewRequests.length, { timeout: 5000 }).toBeGreaterThan(previewBeforeEdit);
-    await expect(page.getByText('Refine meadow item')).toBeVisible();
-    await expect(page.locator('.ui-item-list')).toHaveCount(1);
-
-    const latestSuggest = suggestRequests.at(-1);
-    expect(latestSuggest).toBeDefined();
-    expect(latestSuggest?.postDataJSON()).toMatchObject({ url: BLOG_URL });
-
-    await expect(page).toHaveURL(/\/#\/result\/generated-token$/);
-    await expect(page.locator('.result-shell')).toHaveAttribute('data-state', 'result');
-    await expect(page.getByRole('button', { name: COPY.saveAndGenerate })).toHaveCount(1);
-
-    await urlField.fill(' '.repeat(3));
-    await urlField.blur();
-
-    await expect(page).toHaveURL(/\/#\/create$/);
-    await expect(page.locator('.form-shell')).toHaveAttribute('data-state', 'create');
-    await expect(page.getByLabel(COPY.urlLabel)).toBeVisible();
-    await expect(page.getByRole('heading', { name: COPY.refineSelectors })).toHaveCount(0);
-    await expect(page.getByRole('button', { name: COPY.createFeed })).toBeVisible();
-  });
-
   test('leaves a result when the hash is the retired refine route', async ({ page }) => {
     await createReadyResult(page);
 
diff --git a/frontend/src/__tests__/App.contract.test.tsx b/frontend/src/__tests__/App.contract.test.tsx
index c43258fd..214ec2e7 100644
--- a/frontend/src/__tests__/App.contract.test.tsx
+++ b/frontend/src/__tests__/App.contract.test.tsx
@@ -222,6 +222,7 @@ describe('App contract', () => {
     );
 
     fireEvent.click(screen.getByRole('button', { name: COPY.refineSelectors }));
+    expect(screen.queryByLabelText(COPY.urlLabel)).not.toBeInTheDocument();
     const itemsSelector = await screen.findByLabelText(COPY.itemsSelector);
     await waitFor(() => {
       expect(itemsSelector).toHaveValue('a[href]');
diff --git a/frontend/src/__tests__/ConfigStudio.test.tsx b/frontend/src/__tests__/ConfigStudio.test.tsx
index 5a3efcc6..6b1544d3 100644
--- a/frontend/src/__tests__/ConfigStudio.test.tsx
+++ b/frontend/src/__tests__/ConfigStudio.test.tsx
@@ -1,5 +1,5 @@
 import { describe, it, expect, vi } from 'vitest';
-import { render, screen, fireEvent, waitFor, act, within } from '@testing-library/preact';
+import { render, screen, fireEvent, waitFor, within } from '@testing-library/preact';
 import { http, HttpResponse } from 'msw';
 import type { RefinedSelectorsDocument } from '../api/generated/types.gen';
 import { server } from './mocks/server';
@@ -11,7 +11,7 @@ import {
   validateSuccessBody,
   validateYamlForSelectors,
 } from './mocks/apiFixtures';
-import { ConfigStudio, STUDIO_URL_SETTLE_MS } from '../components/ConfigStudio';
+import { ConfigStudio } from '../components/ConfigStudio';
 import { COPY } from '../journey/copy';
 
 vi.mock('../studio/useStudio', async (importOriginal) => {
@@ -87,26 +87,14 @@ function renderStudio(
   onGenerate = vi.fn<(selectors: RefinedSelectorsDocument) => Promise<void>>(),
   {
     url = pageUrl,
-    onUrlChange = vi.fn(),
-    onUrlCleared = vi.fn(),
     token = 'tok',
   }: {
     url?: string;
-    onUrlChange?: (url: string) => void;
-    onUrlCleared?: () => void;
     token?: string;
   } = {}
 ) {
-  render(
-    <ConfigStudio
-      url={url}
-      token={token}
-      onUrlChange={onUrlChange}
-      onUrlCleared={onUrlCleared}
-      onGenerate={onGenerate}
-    />
-  );
-  return { onGenerate, onUrlChange, onUrlCleared };
+  render(<ConfigStudio url={url} token={token} onGenerate={onGenerate} />);
+  return { onGenerate };
 }
 
 function itemsChip(name = COPY.addSelector('article')) {
@@ -124,7 +112,7 @@ async function waitForItemsChip(name = COPY.addSelector('article')) {
 }
 
 describe('ConfigStudio', () => {
-  it('keeps the page URL and items selector above the preview meadow', async () => {
+  it('keeps the items selector above the preview meadow', async () => {
     echoValidate();
     stubPreview(previewWithImage());
     renderStudio();
@@ -138,13 +126,11 @@ describe('ConfigStudio', () => {
     expect(document.querySelector('.ui-card')).toBeNull();
   });
 
-  it('keeps one rail with the page URL above the items selector', async () => {
+  it('keeps one rail starting with the items selector and no listing URL field', async () => {
     renderStudio();
 
     const items = screen.getByLabelText(COPY.itemsSelector);
-    const urlField = screen.getByLabelText(COPY.urlLabel);
-    expect(urlField).toHaveValue(pageUrl);
-    expect(urlField.compareDocumentPosition(items) & Node.DOCUMENT_POSITION_FOLLOWING).not.toBe(0);
+    expect(screen.queryByLabelText(COPY.urlLabel)).not.toBeInTheDocument();
     expect(document.querySelector('.refine-columns')).toBeNull();
     expect(screen.getByRole('button', { name: COPY.saveAndGenerate })).toBeDisabled();
     expect(screen.queryByRole('combobox')).not.toBeInTheDocument();
@@ -153,6 +139,7 @@ describe('ConfigStudio', () => {
     expect(screen.queryByText(/Strip HTML/i)).not.toBeInTheDocument();
     expect(screen.getByLabelText(COPY.enhanceItems)).toBeInTheDocument();
     await waitFor(() => expect(itemsChip()).toBeInTheDocument());
+    expect(items.compareDocumentPosition(itemsChip()) & Node.DOCUMENT_POSITION_FOLLOWING).not.toBe(0);
     expect(screen.getByRole('button', { name: COPY.fieldMissing(COPY.fieldTitle) })).toBeInTheDocument();
     expect(screen.getByRole('button', { name: COPY.fieldMissing(COPY.fieldLink) })).toBeInTheDocument();
     expect(screen.getByRole('button', { name: COPY.fieldMissing(COPY.fieldPublished) })).toBeInTheDocument();
@@ -161,40 +148,6 @@ describe('ConfigStudio', () => {
     expect(screen.getByRole('button', { name: COPY.saveAndGenerate }).closest('.ui-actions')).not.toBeNull();
   });
 
-  it('re-suggests when the URL settles on a new listing', async () => {
-    vi.useFakeTimers({ shouldAdvanceTime: true });
-    echoValidate();
-    const suggestBodies: unknown[] = [];
-    server.use(
-      http.post('/api/v1/feeds/suggest_selectors', async ({ request }) => {
-        suggestBodies.push(await request.json());
-        return HttpResponse.json(suggestEnvelope());
-      })
-    );
-
-    const { onUrlChange } = renderStudio();
-    await waitFor(() => expect(suggestBodies.length).toBeGreaterThanOrEqual(1));
-
-    fireEvent.input(screen.getByLabelText(COPY.urlLabel), {
-      target: { value: 'https://example.com/blog' },
-    });
-    await act(async () => {
-      await vi.advanceTimersByTimeAsync(STUDIO_URL_SETTLE_MS);
-    });
-
-    expect(onUrlChange).toHaveBeenCalledWith('https://example.com/blog');
-    await waitFor(() => expect(suggestBodies.length).toBeGreaterThanOrEqual(2));
-    expect(suggestBodies.at(-1)).toMatchObject({ url: 'https://example.com/blog' });
-    vi.useRealTimers();
-  });
-
-  it('recovers to create when the URL is cleared on blur', () => {
-    const { onUrlCleared } = renderStudio();
-    fireEvent.input(screen.getByLabelText(COPY.urlLabel), { target: { value: ' '.repeat(3) } });
-    fireEvent.blur(screen.getByLabelText(COPY.urlLabel));
-    expect(onUrlCleared).toHaveBeenCalledTimes(1);
-  });
-
   it('shows a[href] immediately and ranked choices once suggest returns', async () => {
     echoValidate();
     const pendingSuggestion = Promise.withResolvers<Response>();
@@ -463,7 +416,7 @@ describe('ConfigStudio', () => {
     expect(image).toHaveAttribute('src', 'https://cdn.example/a.jpg');
     expect(image).toHaveAttribute('referrerpolicy', 'no-referrer');
     expect(image).toHaveAttribute('loading', 'lazy');
-    expect(image).toHaveAttribute('crossorigin', 'anonymous');
+    expect(image).not.toHaveAttribute('crossorigin');
     expect(screen.getByText('No image')).toBeInTheDocument();
   });
 
@@ -494,8 +447,6 @@ describe('ConfigStudio', () => {
         fallback={<p>Create-time meadow</p>}
         url={pageUrl}
         token="tok"
-        onUrlChange={vi.fn()}
-        onUrlCleared={vi.fn()}
         onGenerate={vi.fn(async () => {})}
       />
     );
@@ -544,6 +495,9 @@ describe('ConfigStudio', () => {
     await waitFor(() => expect(screen.getByText(/selector: a\[href\], article/)).toBeInTheDocument());
     expect(screen.getByText(COPY.yamlCaption)).toBeInTheDocument();
     expect(screen.getByText(/url: https:\/\/example\.com\/articles/)).toBeInTheDocument();
+    const yaml = document.querySelector('pre.refine-yaml');
+    expect(yaml).toHaveClass('ui-card', 'ui-card--notice', 'input--mono');
+    expect(yaml).not.toHaveClass('input');
   });
 
   it('sends the validated selectors when generating a feed', async () => {
diff --git a/frontend/src/__tests__/ResultDisplay.test.tsx b/frontend/src/__tests__/ResultDisplay.test.tsx
index 60c3ca59..032b6385 100644
--- a/frontend/src/__tests__/ResultDisplay.test.tsx
+++ b/frontend/src/__tests__/ResultDisplay.test.tsx
@@ -245,8 +245,6 @@ describe('ResultDisplay', () => {
         studio={{
           token: 'token-1',
           url: 'https://example.com',
-          onUrlChange: vi.fn(),
-          onUrlCleared: vi.fn(),
           onGenerate: vi.fn(async () => {}),
         }}
       />
@@ -266,6 +264,8 @@ describe('ResultDisplay', () => {
 
     expect(refine).toHaveAttribute('aria-expanded', 'true');
     expect(screen.getByLabelText(COPY.itemsSelector)).toBeInTheDocument();
+    expect(screen.queryByLabelText(COPY.urlLabel)).not.toBeInTheDocument();
+    expect(screen.getByRole('button', { name: COPY.createAnother })).toBeInTheDocument();
     expect(screen.getByRole('button', { name: COPY.saveAndGenerate })).toHaveClass('btn--primary');
     expect(document.querySelectorAll('.ui-item-list')).toHaveLength(1);
     const image = document.querySelector('img.refine-sample-image');
@@ -285,8 +285,6 @@ describe('ResultDisplay', () => {
         studio={{
           token: 'token-1',
           url: 'https://example.com',
-          onUrlChange: vi.fn(),
-          onUrlCleared: vi.fn(),
           onGenerate: vi.fn(async () => {}),
         }}
       />
diff --git a/frontend/src/__tests__/appRoute.test.ts b/frontend/src/__tests__/appRoute.test.ts
index b17b8d51..e1e877eb 100644
--- a/frontend/src/__tests__/appRoute.test.ts
+++ b/frontend/src/__tests__/appRoute.test.ts
@@ -116,4 +116,14 @@ describe('appRoute', () => {
     expect(result.current.route).toEqual({ kind: 'create' });
     unmount();
   });
+
+  it('canonicalizes a retired refine hash onto create', () => {
+    history.replaceState({}, '', 'http://localhost:3000/#/refine');
+
+    const { result, unmount } = renderHook(() => useAppRoute());
+
+    expect(location.hash).toBe('#/create');
+    expect(result.current.route).toEqual({ kind: 'create' });
+    unmount();
+  });
 });
diff --git a/frontend/src/components/App.tsx b/frontend/src/components/App.tsx
index 5c38706b..ec2d5e75 100644
--- a/frontend/src/components/App.tsx
+++ b/frontend/src/components/App.tsx
@@ -64,8 +64,6 @@ export function App() {
     onRetryCreate,
     onCreateAnother,
     generateFromStudio,
-    onStudioUrlChange,
-    onStudioUrlCleared,
     onRetryPreview,
     sourceUrl,
     setBookmarkletNotice,
@@ -111,8 +109,6 @@ export function App() {
         ? {
             token,
             url: sourceUrl,
-            onUrlChange: onStudioUrlChange,
-            onUrlCleared: onStudioUrlCleared,
             onGenerate: generateFromStudio,
           }
         : undefined;
diff --git a/frontend/src/components/ConfigStudio.tsx b/frontend/src/components/ConfigStudio.tsx
index f5dff9ec..0474b503 100644
--- a/frontend/src/components/ConfigStudio.tsx
+++ b/frontend/src/components/ConfigStudio.tsx
@@ -21,14 +21,9 @@ import {
 } from '../studio/useStudio';
 import type { StudioIssue, StudioSampleItem, StudioSuggestion } from '../studio/studioService';
 
-/** Settle delay before URL edits re-trigger suggest / validate / preview. */
-export const STUDIO_URL_SETTLE_MS = 400;
-
 interface ConfigStudioProperties {
   readonly url: string;
   readonly token: string;
-  readonly onUrlChange: (url: string) => void;
-  readonly onUrlCleared: () => void;
   readonly onGenerate: (selectors: RefinedSelectorsDocument) => Promise<void>;
   /** Create-time meadow shown until the first studio sample replaces it. */
   readonly fallback?: ComponentChildren;
@@ -40,11 +35,9 @@ interface OpenPanel {
 }
 
 export function ConfigStudio(properties: ConfigStudioProperties) {
-  const { url, token, onUrlChange, onUrlCleared, onGenerate, fallback } = properties;
-  const [urlDraft, setUrlDraft] = useState(url);
-  const [settledUrl, setSettledUrl] = useState(url);
+  const { url, token, onGenerate, fallback } = properties;
   const studio = useStudio({
-    url: settledUrl,
+    url,
     token,
   });
   const { state, suggestion } = studio;
@@ -61,24 +54,6 @@ export function ConfigStudio(properties: ConfigStudioProperties) {
   const nativeFeedUrl = sample?.nativeFeedUrl;
   const isBusy = state.phase === 'validating' || state.phase === 'saving' || state.live.status === 'loading';
 
-  useEffect(() => {
-    setUrlDraft(url);
-    setSettledUrl(url);
-  }, [url]);
-
-  useEffect(() => {
-    const trimmed = urlDraft.trim();
-    if (trimmed === settledUrl.trim()) return;
-
-    const timer = setTimeout(() => {
-      if (!trimmed) return;
-      setSettledUrl(trimmed);
-      onUrlChange(trimmed);
-    }, STUDIO_URL_SETTLE_MS);
-
-    return () => clearTimeout(timer);
-  }, [urlDraft, settledUrl, onUrlChange]);
-
   useEffect(() => {
     if (!panel) return;
     focusElement('studio-field-selector');
@@ -100,29 +75,11 @@ export function ConfigStudio(properties: ConfigStudioProperties) {
     if (unmappedIssues.length > 0) setShowUnmapped(true);
   };
 
-  const onUrlBlur = () => {
-    if (urlDraft.trim()) return;
-    onUrlCleared();
-  };
-
-  const flushUrlBeforeSave = () => {
-    const trimmed = urlDraft.trim();
-    if (!trimmed) {
-      onUrlCleared();
-      return false;
-    }
-    if (trimmed !== settledUrl.trim()) {
-      setSettledUrl(trimmed);
-      onUrlChange(trimmed);
-    }
-    return true;
-  };
-
   const shouldShowCreateMeadow =
     fallback !== undefined && sample === undefined && state.live.status !== 'failed';
   const meadow = shouldShowCreateMeadow ? (
     <>
-      {properties.fallback}
+      {fallback}
       {state.live.status === 'loading' ? (
         <div class="layout-rail-reading">
           <PreviewLoading />
@@ -141,20 +98,6 @@ export function ConfigStudio(properties: ConfigStudioProperties) {
 
   const authoring = (
     <div class="layout-rail-reading layout-stack refine-controls">
-      <label class="field-block" htmlFor="studio-url">
-        <span class="ui-eyebrow">{COPY.urlLabel}</span>
-        <input
-          id="studio-url"
-          class="input input--mono input--lg"
-          type="url"
-          value={urlDraft}
-          spellcheck={false}
-          autoComplete="url"
-          onInput={(event) => setUrlDraft(inputValue(event))}
-          onBlur={onUrlBlur}
-        />
-      </label>
-
       {state.phase === 'failed' ? (
         <Notice title={COPY.createFailedTitle} tone="error">
           {state.message.trim() && state.message !== COPY.createFailedTitle ? (
@@ -227,7 +170,6 @@ export function ConfigStudio(properties: ConfigStudioProperties) {
           class="btn btn--primary"
           disabled={!canSaveStudio(state)}
           onClick={() => {
-            if (!flushUrlBeforeSave()) return;
             void studio.save(onGenerate);
           }}
         >
@@ -257,7 +199,7 @@ export function ConfigStudio(properties: ConfigStudioProperties) {
         </button>
         {yamlOpen ? (
           <>
-            <pre class="refine-yaml input input--mono">{state.yaml}</pre>
+            <pre class="refine-yaml ui-card ui-card--notice input--mono">{state.yaml}</pre>
             <button
               type="button"
               class="btn btn--quiet btn--linkish"
diff --git a/frontend/src/components/PreviewItem.tsx b/frontend/src/components/PreviewItem.tsx
index ec827abf..0de97384 100644
--- a/frontend/src/components/PreviewItem.tsx
+++ b/frontend/src/components/PreviewItem.tsx
@@ -42,7 +42,6 @@ function SampleImage({ url }: { readonly url: string }) {
       src={url}
       referrerPolicy="no-referrer"
       loading="lazy"
-      crossOrigin="anonymous"
       onError={() => setVisible(false)}
     />
   );
diff --git a/frontend/src/components/ResultDisplay.tsx b/frontend/src/components/ResultDisplay.tsx
index fa9ac7ee..7479ccce 100644
--- a/frontend/src/components/ResultDisplay.tsx
+++ b/frontend/src/components/ResultDisplay.tsx
@@ -12,8 +12,6 @@ import { PreviewItem } from './PreviewItem';
 export interface AuthenticatedStudioCapability {
   readonly token: string;
   readonly url: string;
-  readonly onUrlChange: (url: string) => void;
-  readonly onUrlCleared: () => void;
   readonly onGenerate: (selectors: RefinedSelectorsDocument) => Promise<void>;
 }
 
@@ -144,8 +142,6 @@ export function ResultDisplay({
             <ConfigStudio
               url={studio.url}
               token={studio.token}
-              onUrlChange={studio.onUrlChange}
-              onUrlCleared={studio.onUrlCleared}
               onGenerate={studio.onGenerate}
               fallback={refineOpen ? meadow : undefined}
             />
diff --git a/frontend/src/feed/useFeedFlow.ts b/frontend/src/feed/useFeedFlow.ts
index f4f16d22..45a796ea 100644
--- a/frontend/src/feed/useFeedFlow.ts
+++ b/frontend/src/feed/useFeedFlow.ts
@@ -307,15 +307,6 @@ export function useFeedFlow({
       setFocusCreateComposerKey((current) => current + 1);
       navigate({ kind: 'create', prefillUrl: feedFormData.url || undefined });
     },
-    onStudioUrlChange: (nextUrl: string) => {
-      onFeedFieldChange('url', nextUrl);
-    },
-    onStudioUrlCleared: () => {
-      setFeedFormData({ url: '' });
-      clearFeedDraftState();
-      clearResult();
-      navigate({ kind: 'create' }, { replace: true });
-    },
     generateFromStudio,
     onRetryPreview: retryPreviewFetch,
     sourceUrl,
diff --git a/frontend/src/routes/appRoute.ts b/frontend/src/routes/appRoute.ts
index 27ec38db..ab704aad 100644
--- a/frontend/src/routes/appRoute.ts
+++ b/frontend/src/routes/appRoute.ts
@@ -91,7 +91,12 @@ export function useAppRoute() {
 
     const canonicalize = (source: 'mount' | 'navigation') => {
       const nextRoute = readAppRoute();
-      const needsReplace = !location.hash || location.pathname !== '/' || location.hash.startsWith('#!');
+      const canonicalHref = buildAppRouteHref(nextRoute);
+      const needsReplace =
+        !location.hash ||
+        location.pathname !== '/' ||
+        location.hash.startsWith('#!') ||
+        location.href !== canonicalHref;
 
       if (needsReplace) replaceRoute(nextRoute);
       setRoute(nextRoute);

From c91f18794d45294f3fe33e586f5966c20bc5a1e4 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Mon, 21 Sep 2026 18:06:23 +0200
Subject: [PATCH 075/108] docs(plan): persist the studio architecture cleanup
 carrier

Record the approved ownership fixes and the save recovery so each phase can land as its own commit.
---
 .agents/plan/studio-architecture-cleanup.md | 356 ++++++++++++++++++++
 1 file changed, 356 insertions(+)
 create mode 100644 .agents/plan/studio-architecture-cleanup.md

diff --git a/.agents/plan/studio-architecture-cleanup.md b/.agents/plan/studio-architecture-cleanup.md
new file mode 100644
index 00000000..ba5173d5
--- /dev/null
+++ b/.agents/plan/studio-architecture-cleanup.md
@@ -0,0 +1,356 @@
+# Implementation Plan: studio-architecture-cleanup
+
+Intent: inline
+Circuit breaker approved: false
+
+## Product stance
+
+Recommendation: Build Now
+
+- Persona and path: Sam’s documented SPA path stays Create → token (if needed) → Result → Copy feed URL (`docs/personas.md`). This tranche does not add a journey step. It restores the result panel after a successful save and removes duplicate owners that can make preview, serve, and the published contract disagree.
+- Interaction budget: qualitative. A successful **Save and generate feed** returns the button to that label instead of leaving **Creating…** stuck. No new click.
+- Concept budget: zero new concepts. Selector refinement stays on `#/result/:token`. There is still no `#/refine` route.
+- Forced challenge: weighting `POST /api/v1/feeds` as a live fetch lowers the default create budget from 60/min to 12/min. That matches the stated purpose of the live-fetch cost table (protect HTTP/browser extraction). Admit-then-charge stays: a budget of N can overrun by cost minus 1.
+- Non-goals: no forced preview refetch on **Check again** (that needs a new wire field); no change to `adoptServerDraft` (server owns items and enhance, client owns field selectors); no relitigating inline result refinement or the absent `#/refine` route (settled in `.agents/plan/inline-result-refinement.md` and `.agents/plan/gate-result-refinement.md`).
+
+## Intent constraints
+
+- A successful studio generate returns the same `ConfigStudio` instance to an editing, validated phase. A stale `saveRequestReference` does not overwrite a newer save.
+- The user-facing save label returns to **Save and generate feed**. The user-facing parse failure stays `COPY.unableToCompleteCreation`.
+- `Feeds::GeneratorInput` is the only owner of token strategy resolution, including a nil strategy and `SUPPORTED_STRATEGIES`.
+- Studio 429 bodies are API-shaped for every `FeedRoutes::STUDIO_POSTS` path. `POST /api/v1/feeds` costs the same live-fetch weight as preview and suggest.
+- One bounded JSON reader owns `MAX_BODY_BYTES`. Create and studio posts both use it.
+- Preview samples, including the 10-item cap, have one Ruby owner. OpenAPI candidate buckets, sample keys, issue codes, and `RefinedSelectorKey` are stamped from runtime constants. `RefinedSelectorsDocument` accepts what the server accepts, including gsub post-processors.
+- `live` is orthogonal to studio phase. `canSaveStudio` and `studioIssues` stay the read accessors.
+- An aged preview-page slot refetches. An unchanged body does not rewrite the temp file. The temp file is removed on process exit. No new wire field.
+
+## Classification and architecture
+
+- Classification: `design`. Inherited from the approved plan. Do not relitigate.
+- Runtime route: `ruby-dev` and `typescript-dev`. Not Rails.
+- Architecture branch: `deep-modules` (single ownership, deletion test, locality, wire versus domain).
+- Ownership decisions:
+  - `Feeds::GeneratorInput` owns default strategy name and the supported-strategy check. `PreviewFeed` and `SourceResolver` stop duplicating that rule. `for_token` resolves a nil strategy.
+  - `FeedRoutes::STUDIO_POSTS` owns the studio POST set. `RateLimiter` derives its studio paths from that constant. Create’s live-fetch cost is an explicit table entry because create is not a `STUDIO_POSTS` key.
+  - `Api::V1::JsonBody` owns the bounded JSON body read and `MAX_BODY_BYTES`.
+  - `Api::V1::PreviewSamples` owns RSS-to-sample mapping and `SAMPLE_LIMIT`. `PreviewFeed` stays the request handler.
+  - `SuggestSelectors` owns candidate bucket names. `PreviewSamples` owns sample item keys. `OpenapiRuntimeContract` / `OpenapiStudioSchemas` stamp those facts; they do not re-list them.
+  - `useStudio` owns studio phase and live preview as orthogonal fields. `assignLive` and `requestSuggestion` go away. `ConfigStudio` owns the open field as `StudioFieldId | undefined`.
+  - `studioService` owns wire-to-domain parsing. A field-naming helper distinguishes a bad `sample_items` from a bad `candidates` without changing the user-facing message.
+  - `PreviewPageCache` owns slot freshness and the temp file. Check again does not gain a refetch flag.
+- Later mutation of a path is required only where a later phase changes a different fact in the same file. Those paths are listed under Shared files.
+
+## Acceptance
+
+- Given a successful generate, when the result panel stays mounted, then the primary action reads **Save and generate feed** and another save can run.
+- Given an older save finishing after a newer one, when the stale request settles, then it does not replace the newer phase.
+- Given a token with a nil strategy, when serve and preview expand it, then both call `GeneratorInput.for_token` and receive the same resolved strategy. The parity example does not pass a precomputed strategy in.
+- Given any `STUDIO_POSTS` path, when the rate limiter returns 429, then the body is API-shaped. Given `POST /api/v1/feeds`, when it is admitted, then it consumes the live-fetch weight. A budget of N can still overrun by cost minus 1.
+- Given a body over the byte cap, when create or a studio post reads it, then both use `JsonBody`.
+- Given RSS items, when preview maps them, then `PreviewSamples` produces at most 10 rows. Given a gsub post-processor, when the OpenAPI document is published, then `RefinedSelectorsDocument` allows it.
+- Given a selector edit, when only live preview changes, then phase is not rebuilt by a variant switch.
+- Given a malformed `sample_items` or `candidates` payload, when parsing fails, then the thrown error names the field and the message stays `COPY.unableToCompleteCreation`.
+- Given a cached preview page older than the TTL, when preview runs again, then it fetches. Given the same body, when store runs again, then the temp file is not rewritten. Given process exit, when the slot still exists, then the temp file is removed.
+
+## Shared files
+
+These paths appear in more than one phase because each phase changes a different fact:
+
+- `frontend/src/studio/useStudio.ts` — Phase 01 adds the save success branch; Phase 07 flattens state around it; Phase 08 deletes `requestSuggestion`.
+- `frontend/src/__tests__/useStudio.test.ts` — Phase 01 covers save recovery; Phase 07 covers the flattened state.
+- `frontend/src/components/ConfigStudio.tsx` — Phase 07 adjusts call sites if the flattened state requires it; Phase 08 collapses the open panel.
+- `app/web/api/v1/preview_feed.rb` — Phase 02 deletes duplicated strategy resolution; Phase 05 moves sample mapping out.
+- `spec/html2rss/web/api/v1_spec.rb` — Phase 02 derives preview strategy through `GeneratorInput`; Phase 10 extends cache examples.
+- `app/web/api/v1/preview_samples.rb` — Phase 05 creates the module; Phase 11 adds the sample-limit cross-reference.
+
+## Conditional risks
+
+- Observability: N/A. No APM, tracing, or logging contract changes.
+- Security: authn/authz rules stay on `StudioRequest`. The body cap moves without raising it. Create weighting tightens the live-fetch budget. `spec/html2rss/web/api/studio_auth_chain_spec.rb` remains the security chain.
+- Pre-ship: Phase 12 runs `make openapi-client` then `make ci-ready` inside the Dev Container, then smokes guest result, member result collapsed, member result open, and post-save recovery at `http://127.0.0.1:4001/`.
+- All `verification_gate` commands run inside the Dev Container. A host-only exit is not a pass.
+
+<!-- phase:start -->
+
+## Phase 01 — Return studio save to editing after success
+
+Add the `useStudio.save` success branch so a successful generate sets editing and validated. Ignore a stale `saveRequestReference`. Assert recovery in `useStudio.test.ts` and that the button returns to **Save and generate feed** in `ConfigStudio.test.tsx`.
+
+target_files:
+
+- `frontend/src/studio/useStudio.ts`
+- `frontend/src/__tests__/useStudio.test.ts`
+- `frontend/src/__tests__/ConfigStudio.test.tsx`
+
+read_context:
+
+- `frontend/src/components/ConfigStudio.tsx`
+- `frontend/src/feed/useFeedFlow.ts`
+- `frontend/src/journey/copy.ts`
+
+verification_gate: `make test-frontend-unit`
+commit_message: `fix(studio): return to editing after a successful save`
+
+<!-- phase:end -->
+
+<!-- phase:start -->
+
+## Phase 02 — Own token strategy resolution in GeneratorInput
+
+Move the default strategy name and the `SUPPORTED_STRATEGIES` check into `Feeds::GeneratorInput`. `for_token` resolves a nil strategy. Delete the copies in `PreviewFeed` and `SourceResolver`. The parity example derives strategy through that owner.
+
+target_files:
+
+- `app/web/feeds/generator_input.rb`
+- `app/web/feeds/source_resolver.rb`
+- `app/web/api/v1/preview_feed.rb`
+- `spec/html2rss/web/feeds/generator_input_spec.rb`
+- `spec/html2rss/web/feeds/source_resolver_spec.rb`
+- `spec/html2rss/web/api/v1_spec.rb`
+
+read_context:
+
+- `app/web/api/v1/preview_page_cache.rb`
+- `app/web/security/feed_token.rb`
+
+verification_gate: `bundle exec rspec spec/html2rss/web/feeds/generator_input_spec.rb spec/html2rss/web/feeds/source_resolver_spec.rb spec/html2rss/web/api/v1_spec.rb`
+commit_message: `refactor(feeds): own token strategy resolution in GeneratorInput`
+
+<!-- phase:end -->
+
+<!-- phase:start -->
+
+## Phase 03 — Derive studio rate-limit paths and weight create
+
+Derive the studio path set from `FeedRoutes::STUDIO_POSTS`. Add `POST /api/v1/feeds` to the live-fetch cost table. Document that admit-then-charge lets a budget of N overrun by cost minus 1. Do not change that behavior. A studio POST is API-shaped on 429, and create is weighted.
+
+target_files:
+
+- `app/web/request/rate_limiter.rb`
+- `spec/html2rss/web/rate_limiter_spec.rb`
+
+read_context:
+
+- `app/web/routes/api_v1/feed_routes.rb`
+- `docs/README.md`
+
+verification_gate: `bundle exec rspec spec/html2rss/web/rate_limiter_spec.rb`
+commit_message: `fix(api): weight feed creation as a live fetch`
+
+<!-- phase:end -->
+
+<!-- phase:start -->
+
+## Phase 04 — Share one bounded JSON body reader
+
+Add `Api::V1::JsonBody` as the owner of `MAX_BODY_BYTES` and the limited read. `StudioRequest` and `CreateFeed` both use it. Update the auth-chain spec that names `CreateFeed::MAX_BODY_BYTES`.
+
+target_files:
+
+- `app/web/api/v1/json_body.rb`
+- `app/web/api/v1/studio_request.rb`
+- `app/web/api/v1/create_feed.rb`
+- `spec/html2rss/web/api/studio_auth_chain_spec.rb`
+- `spec/html2rss/web/api/json_body_spec.rb`
+
+read_context:
+
+- `app/web/routes/api_v1/feed_routes.rb`
+
+verification_gate: `bundle exec rspec spec/html2rss/web/api`
+commit_message: `refactor(api): share one bounded JSON body reader`
+
+<!-- phase:end -->
+
+<!-- phase:start -->
+
+## Phase 05 — Move RSS sample mapping into PreviewSamples
+
+Extract RSS-to-sample mapping from `PreviewFeed` into `Api::V1::PreviewSamples`, including `SAMPLE_LIMIT` and the sample key list. Add a focused spec.
+
+target_files:
+
+- `app/web/api/v1/preview_samples.rb`
+- `app/web/api/v1/preview_feed.rb`
+- `spec/html2rss/web/api/preview_samples_spec.rb`
+
+read_context:
+
+- `spec/support/openapi_studio_schemas.rb`
+- `spec/html2rss/web/api/v1_spec.rb`
+
+verification_gate: `bundle exec rspec spec/html2rss/web/api spec/html2rss/web/openapi_post_processor_spec.rb`
+commit_message: `refactor(api): own preview samples outside the handler`
+
+<!-- phase:end -->
+
+<!-- phase:start -->
+
+## Phase 06 — Stamp studio OpenAPI schemas from runtime owners
+
+Derive candidate bucket names from the constant on `SuggestSelectors`. Derive `PreviewSampleItem` keys from `PreviewSamples`. Publish `RefinedSelectorsDocument` wide enough for the gsub post-processors the server accepts. Add stamp tests for the candidates rewrite, issue codes, and `RefinedSelectorKey`. Move `openapi_runtime_contract_spec.rb` out of `spec/support`. Regenerate `public/openapi.yaml`. Do not hand-edit that YAML.
+
+target_files:
+
+- `app/web/api/v1/suggest_selectors.rb`
+- `spec/support/openapi_studio_schemas.rb`
+- `spec/support/openapi.rb`
+- `spec/support/openapi_runtime_contract_spec.rb`
+- `spec/html2rss/web/openapi_runtime_contract_spec.rb`
+- `public/openapi.yaml`
+
+read_context:
+
+- `app/web/api/v1/preview_samples.rb`
+- `spec/html2rss/web/security/refined_selectors_spec.rb`
+- `spec/support/openapi_post_processor.rb`
+- `spec/html2rss/web/openapi_post_processor_spec.rb`
+
+verification_gate: `make openapi && bundle exec rspec spec/html2rss/web/openapi_runtime_contract_spec.rb spec/html2rss/web/openapi_post_processor_spec.rb && make openapi-lint`
+commit_message: `fix(openapi): stamp studio schemas from runtime owners`
+
+<!-- phase:end -->
+
+<!-- phase:start -->
+
+## Phase 07 — Keep live preview orthogonal to studio phase
+
+Reshape `StudioState` so live is orthogonal to phase. Delete `assignLive`. Collapse the hand-copied `setState` calls to phase deltas. Keep `canSaveStudio` and `studioIssues`.
+
+target_files:
+
+- `frontend/src/studio/useStudio.ts`
+- `frontend/src/__tests__/useStudio.test.ts`
+- `frontend/src/components/ConfigStudio.tsx`
+
+read_context:
+
+- `frontend/src/__tests__/ConfigStudio.test.tsx`
+- `frontend/src/studio/selectorDraft.ts`
+
+verification_gate: `make test-frontend-unit`
+commit_message: `refactor(studio): keep live preview orthogonal to phase`
+
+<!-- phase:end -->
+
+<!-- phase:start -->
+
+## Phase 08 — Delete unused studio suggestion and panel nonce
+
+Delete unused `requestSuggestion` from `useStudio`. Collapse `OpenPanel` to `StudioFieldId | undefined`.
+
+target_files:
+
+- `frontend/src/studio/useStudio.ts`
+- `frontend/src/components/ConfigStudio.tsx`
+
+read_context:
+
+- `frontend/src/__tests__/useStudio.test.ts`
+- `frontend/src/__tests__/ConfigStudio.test.tsx`
+- `CONTEXT.md`
+
+verification_gate: `make test-frontend-unit && make lint-js`
+commit_message: `refactor(studio): drop unused suggestion and panel nonce`
+
+<!-- phase:end -->
+
+<!-- phase:start -->
+
+## Phase 09 — Name the studio field when parsing fails
+
+Replace the identical throws in `studioService.ts` with one field-naming helper so a bad `sample_items` is distinguishable from a bad `candidates`. Keep the user-facing message on `COPY.unableToCompleteCreation`.
+
+target_files:
+
+- `frontend/src/studio/studioService.ts`
+- `frontend/src/__tests__/studioService.test.ts`
+
+read_context:
+
+- `frontend/src/journey/copy.ts`
+- `frontend/src/studio/useStudio.ts`
+
+verification_gate: `make test-frontend-unit`
+commit_message: `fix(studio): name the field when a studio payload fails to parse`
+
+<!-- phase:end -->
+
+<!-- phase:start -->
+
+## Phase 10 — Expire cached preview pages and keep the temp file
+
+Add a TTL so an aged slot refetches. Skip rewriting the temp file when the stored body is unchanged. Remove the temp file on process exit. Extend the existing `v1_spec` cache examples. Do not add a wire field for forced refetch.
+
+target_files:
+
+- `app/web/api/v1/preview_page_cache.rb`
+- `spec/html2rss/web/api/v1_spec.rb`
+
+read_context:
+
+- `app/web/api/v1/preview_feed.rb`
+
+verification_gate: `bundle exec rspec spec/html2rss/web/api/v1_spec.rb`
+commit_message: `fix(studio): expire cached preview pages and drop the temp file`
+
+<!-- phase:end -->
+
+<!-- phase:start -->
+
+## Phase 11 — Record studio ownership and limit decisions
+
+`CONTEXT.md` Config Studio records validate-echo ownership and the silent non-blocking suggest failure. `docs/README.md` records create weighting and the preview cache TTL. Cross-reference the 10-item sample limit between `PreviewSamples` and `feedParsers.ts`.
+
+target_files:
+
+- `CONTEXT.md`
+- `docs/README.md`
+- `app/web/api/v1/preview_samples.rb`
+- `frontend/src/feeds/feedParsers.ts`
+
+read_context:
+
+- `app/web/request/rate_limiter.rb`
+- `app/web/api/v1/preview_page_cache.rb`
+- `frontend/src/studio/useStudio.ts`
+
+verification_gate: `make ready`
+commit_message: `docs(studio): record validate-echo ownership and preview limits`
+
+<!-- phase:end -->
+
+<!-- phase:start -->
+
+## Phase 12 — Regenerate the client and run the CI gate
+
+Regenerate the frontend OpenAPI client, then run `make ci-ready` inside the Dev Container. Smoke guest result, member result collapsed, member result with the panel open, and post-save recovery at `http://127.0.0.1:4001/`.
+
+target_files:
+
+- `frontend/src/api/generated/client.gen.ts`
+- `frontend/src/api/generated/index.ts`
+- `frontend/src/api/generated/sdk.gen.ts`
+- `frontend/src/api/generated/types.gen.ts`
+- `frontend/src/api/generated/client/client.gen.ts`
+- `frontend/src/api/generated/client/index.ts`
+- `frontend/src/api/generated/client/types.gen.ts`
+- `frontend/src/api/generated/client/utils.gen.ts`
+- `frontend/src/api/generated/core/auth.gen.ts`
+- `frontend/src/api/generated/core/bodySerializer.gen.ts`
+- `frontend/src/api/generated/core/params.gen.ts`
+- `frontend/src/api/generated/core/pathSerializer.gen.ts`
+- `frontend/src/api/generated/core/queryKeySerializer.gen.ts`
+- `frontend/src/api/generated/core/serverSentEvents.gen.ts`
+- `frontend/src/api/generated/core/types.gen.ts`
+- `frontend/src/api/generated/core/utils.gen.ts`
+
+read_context:
+
+- `public/openapi.yaml`
+- `frontend/openapi-ts.config.ts`
+
+verification_gate: `make openapi-client && make ci-ready`
+commit_message: `chore(api): regenerate the studio OpenAPI client`
+
+<!-- phase:end -->

From 06095efe92e79e8f2cd9355f47218eb25454534d Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Mon, 21 Sep 2026 18:08:00 +0200
Subject: [PATCH 076/108] fix(studio): return to editing after a successful
 save

A successful generate left the mounted result panel on Creating because save only wrote state in the catch path.
---
 frontend/src/__tests__/ConfigStudio.test.tsx |  1 +
 frontend/src/__tests__/useStudio.test.ts     | 65 +++++++++++++++++++-
 frontend/src/studio/useStudio.ts             |  8 +++
 3 files changed, 73 insertions(+), 1 deletion(-)

diff --git a/frontend/src/__tests__/ConfigStudio.test.tsx b/frontend/src/__tests__/ConfigStudio.test.tsx
index 6b1544d3..e2c18a54 100644
--- a/frontend/src/__tests__/ConfigStudio.test.tsx
+++ b/frontend/src/__tests__/ConfigStudio.test.tsx
@@ -514,5 +514,6 @@ describe('ConfigStudio', () => {
     await waitFor(() => expect(onGenerate).toHaveBeenCalled());
     expect(onGenerate.mock.calls[0]?.[0]).toEqual({ items: { selector: 'a[href], article' } });
     expect(screen.getByLabelText(COPY.enhanceItems)).not.toBeChecked();
+    await waitFor(() => expect(screen.getByRole('button', { name: COPY.saveAndGenerate })).toBeEnabled());
   });
 });
diff --git a/frontend/src/__tests__/useStudio.test.ts b/frontend/src/__tests__/useStudio.test.ts
index e0de1cfc..fe698a7e 100644
--- a/frontend/src/__tests__/useStudio.test.ts
+++ b/frontend/src/__tests__/useStudio.test.ts
@@ -7,7 +7,12 @@ import {
   selectorsFromDraft,
   withFieldSelector,
 } from '../studio/selectorDraft';
-import { STUDIO_PREVIEW_SETTLE_MS, STUDIO_VALIDATE_DELAY_MS, useStudio } from '../studio/useStudio';
+import {
+  STUDIO_PREVIEW_SETTLE_MS,
+  STUDIO_VALIDATE_DELAY_MS,
+  canSaveStudio,
+  useStudio,
+} from '../studio/useStudio';
 import { httpRequestUrl } from '../api/http/client';
 
 const pageUrl = 'https://example.com/articles';
@@ -646,6 +651,64 @@ describe('useStudio', () => {
     expect(result.current.state.draft.enhance).toBe(true);
   });
 
+  it('returns to a save-enabled editing phase after generate', async () => {
+    vi.useFakeTimers();
+    mockStudioFetch(fetchMock);
+    const { result } = renderHook(() => useStudio({ url: pageUrl, token, validateDelayMs: 0 }));
+    await advanceValidate(0);
+    expect(canSaveStudio(result.current.state)).toBe(true);
+
+    await act(async () => {
+      await result.current.save(async () => {});
+    });
+
+    expect(result.current.state.phase).toBe('editing');
+    const state = result.current.state;
+    if (state.phase !== 'editing') return;
+    expect(state.validated).toBe(true);
+    expect(canSaveStudio(state)).toBe(true);
+  });
+
+  it('ignores a stale save after a newer save starts', async () => {
+    vi.useFakeTimers();
+    mockStudioFetch(fetchMock);
+    const { result } = renderHook(() => useStudio({ url: pageUrl, token, validateDelayMs: 0 }));
+    await advanceValidate(0);
+
+    let resolveStale: (() => void) | undefined;
+    const stale = new Promise<void>((resolve) => {
+      resolveStale = resolve;
+    });
+    let resolveCurrent: (() => void) | undefined;
+    const current = new Promise<void>((resolve) => {
+      resolveCurrent = resolve;
+    });
+
+    act(() => {
+      void result.current.save(() => stale);
+    });
+    act(() => {
+      void result.current.save(() => current);
+    });
+    expect(result.current.state.phase).toBe('saving');
+
+    await act(async () => {
+      resolveStale?.();
+      await stale;
+    });
+    expect(result.current.state.phase).toBe('saving');
+
+    await act(async () => {
+      resolveCurrent?.();
+      await current;
+    });
+    expect(result.current.state.phase).toBe('editing');
+    const state = result.current.state;
+    if (state.phase !== 'editing') return;
+    expect(state.validated).toBe(true);
+    expect(canSaveStudio(state)).toBe(true);
+  });
+
   it('fails closed when validate is unauthorized', async () => {
     fetchMock.mockImplementation(() =>
       Promise.resolve(
diff --git a/frontend/src/studio/useStudio.ts b/frontend/src/studio/useStudio.ts
index 8964a947..1428288c 100644
--- a/frontend/src/studio/useStudio.ts
+++ b/frontend/src/studio/useStudio.ts
@@ -295,6 +295,14 @@ export function useStudio({
 
     try {
       await create(selectorsFromDraft(current.draft));
+      if (saveRequestReference.current !== requestId) return;
+      setState({
+        phase: 'editing',
+        draft: current.draft,
+        yaml: current.yaml,
+        validated: true,
+        live: current.live,
+      });
     } catch (error) {
       if (saveRequestReference.current !== requestId) return;
       setState({

From cbdb0bdfca975738b5175cc253f1ae299a676396 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Mon, 21 Sep 2026 18:09:46 +0200
Subject: [PATCH 077/108] refactor(feeds): own token strategy resolution in
 GeneratorInput

Serve and preview were each choosing the default strategy, so the parity example could not catch a divergence.
---
 app/web/api/v1/preview_feed.rb                |  8 +----
 app/web/feeds/generator_input.rb              | 34 +++++++++++++++++--
 app/web/feeds/source_resolver.rb              | 23 +------------
 spec/html2rss/web/api/v1_spec.rb              |  7 ++--
 .../web/feeds/generator_input_spec.rb         | 20 +++++++++--
 5 files changed, 52 insertions(+), 40 deletions(-)

diff --git a/app/web/api/v1/preview_feed.rb b/app/web/api/v1/preview_feed.rb
index ee00a87f..7dda2473 100644
--- a/app/web/api/v1/preview_feed.rb
+++ b/app/web/api/v1/preview_feed.rb
@@ -37,7 +37,7 @@ def call(request)
             # @param selectors [Object]
             # @return [Hash{Symbol=>Object}]
             def preview_config(url, selectors)
-              Feeds::GeneratorInput.for_token(url:, strategy: default_strategy, selectors: refined(selectors))
+              Feeds::GeneratorInput.for_token(url:, selectors: refined(selectors))
             end
 
             # @param selectors [Object]
@@ -48,12 +48,6 @@ def refined(selectors)
               RefinedSelectors.from_client({ selectors: })
             end
 
-            # @return [String]
-            def default_strategy
-              configured = Html2rss::Config.default_strategy_name.to_s
-              configured.strip.empty? ? 'auto' : configured
-            end
-
             # Selected fields only. {Html2rss::Test::Result#to_h} also carries +rss+.
             # Successful previews rebuild the meadow from that RSS, capped here.
             #
diff --git a/app/web/feeds/generator_input.rb b/app/web/feeds/generator_input.rb
index 8b393966..bb6ea393 100644
--- a/app/web/feeds/generator_input.rb
+++ b/app/web/feeds/generator_input.rb
@@ -9,24 +9,52 @@ module Feeds
       # Serve and studio preview both call {.for_token} so a preview cannot
       # diverge from the feed a reader later receives.
       module GeneratorInput
+        SUPPORTED_STRATEGIES = Set.new(Html2rss::RequestService.strategy_names.map(&:to_s)).freeze
+        private_constant :SUPPORTED_STRATEGIES
+
         class << self
           ##
           # Builds the generator config for a signed token feed.
           #
+          # A nil or blank +strategy+ resolves to the configured default, or +auto+
+          # when that default is blank. An explicit name must be supported.
+          #
           # @param url [String] channel URL bound to the token
-          # @param strategy [String, Symbol] resolved request strategy
+          # @param strategy [String, Symbol, nil] token strategy, or nil for the configured default
           # @param selectors [Html2rss::Web::RefinedSelectors, nil] signed selector fragment
           # @return [Hash{Symbol=>Object}]
-          def for_token(url:, strategy:, selectors: nil)
+          def for_token(url:, strategy: nil, selectors: nil)
             expanded = LocalConfig.global.slice(:stylesheets, :headers).merge(
               channel: { url: },
               auto_source: {},
-              strategy: strategy.to_sym
+              strategy: resolve_strategy(strategy).to_sym
             )
             return expanded if selectors.nil? || selectors.empty?
 
             expanded.merge(selectors.to_config_fragment)
           end
+
+          private
+
+          # @param strategy [String, Symbol, nil]
+          # @return [String]
+          # @raise [Html2rss::Web::BadRequestError] when the name is not supported
+          def resolve_strategy(strategy)
+            name = strategy.to_s.strip
+            return default_strategy_name if name.empty?
+            return name if name == default_strategy_name
+            raise Html2rss::Web::BadRequestError, 'Unsupported strategy' unless SUPPORTED_STRATEGIES.include?(name)
+
+            name
+          end
+
+          # @return [String]
+          def default_strategy_name
+            configured = Html2rss::Config.default_strategy_name.to_s
+            return configured unless configured.strip.empty?
+
+            'auto'
+          end
         end
       end
     end
diff --git a/app/web/feeds/source_resolver.rb b/app/web/feeds/source_resolver.rb
index 79a438d8..7c31a8c3 100644
--- a/app/web/feeds/source_resolver.rb
+++ b/app/web/feeds/source_resolver.rb
@@ -8,8 +8,6 @@ module Feeds
       ##
       # Resolves static and token-backed requests into shared generator inputs.
       module SourceResolver
-        SUPPORTED_STRATEGIES = Set.new(Html2rss::RequestService.strategy_names.map(&:to_s)).freeze
-
         class << self
           # @param feed_request [Html2rss::Web::Feeds::Contracts::Request]
           # @return [Html2rss::Web::Feeds::Contracts::ResolvedSource]
@@ -84,7 +82,7 @@ def expanded_generator_input(feed_token)
             selectors = feed_token.selectors
             GeneratorInput.for_token(
               url: feed_token.url,
-              strategy: resolved_strategy(feed_token),
+              strategy: feed_token.strategy,
               selectors: selectors.nil? ? nil : RefinedSelectors.from_verified_wire(selectors.to_wire)
             )
           end
@@ -141,25 +139,6 @@ def authorize_feed_token!(token)
 
             raise Html2rss::Web::ForbiddenError, 'Access Denied'
           end
-
-          # @param feed_token [Html2rss::Web::FeedToken]
-          # @return [String]
-          def resolved_strategy(feed_token)
-            strategy = feed_token.strategy.to_s.strip
-            return default_strategy_name if strategy.empty?
-            return strategy if strategy == default_strategy_name
-            raise Html2rss::Web::BadRequestError, 'Unsupported strategy' unless SUPPORTED_STRATEGIES.include?(strategy)
-
-            strategy
-          end
-
-          # @return [String]
-          def default_strategy_name
-            configured = Html2rss::Config.default_strategy_name.to_s
-            return configured unless configured.strip.empty?
-
-            'auto'
-          end
         end
       end
     end
diff --git a/spec/html2rss/web/api/v1_spec.rb b/spec/html2rss/web/api/v1_spec.rb
index fcdd4e3f..cc2f9c42 100644
--- a/spec/html2rss/web/api/v1_spec.rb
+++ b/spec/html2rss/web/api/v1_spec.rb
@@ -1041,8 +1041,7 @@ def post_preview(url)
     end
 
     def preview_strategy
-      name = Html2rss::Config.default_strategy_name.to_s
-      (name.strip.empty? ? 'auto' : name).to_sym
+      Html2rss::Web::Feeds::GeneratorInput.for_token(url: feed_url, strategy: nil)[:strategy]
     end
 
     def record_preview_results(results)
@@ -1156,10 +1155,8 @@ def rejected_page_results
       selectors = Html2rss::Web::RefinedSelectors.from_client(selectors: { items: { selector: 'article' } })
       post '/api/v1/feeds/preview', { url: feed_url, selectors: { items: { selector: 'article' } } }.to_json
 
-      strategy = Html2rss::Config.default_strategy_name.to_s
-      strategy = 'auto' if strategy.strip.empty?
       expect(Html2rss).to have_received(:test).with(
-        Html2rss::Web::Feeds::GeneratorInput.for_token(url: feed_url, strategy:, selectors:),
+        Html2rss::Web::Feeds::GeneratorInput.for_token(url: feed_url, selectors:),
         min_items: 1
       )
     end
diff --git a/spec/html2rss/web/feeds/generator_input_spec.rb b/spec/html2rss/web/feeds/generator_input_spec.rb
index 381ae3a7..f38d0393 100644
--- a/spec/html2rss/web/feeds/generator_input_spec.rb
+++ b/spec/html2rss/web/feeds/generator_input_spec.rb
@@ -39,9 +39,23 @@
       )
     end
 
+    it 'resolves a nil strategy without a caller-supplied name', :aggregate_failures do
+      allow(Html2rss::Config).to receive(:default_strategy_name).and_return('botasaurus')
+
+      expect(described_class.for_token(url:)[:strategy]).to eq(:botasaurus)
+
+      allow(Html2rss::Config).to receive(:default_strategy_name).and_return(nil)
+      expect(described_class.for_token(url:, strategy: nil)[:strategy]).to eq(:auto)
+    end
+
+    it 'rejects an unsupported explicit strategy' do
+      expect { described_class.for_token(url:, strategy: 'nope') }
+        .to raise_error(Html2rss::Web::BadRequestError, 'Unsupported strategy')
+    end
+
     context 'when serve and preview expand the same token' do
       let(:feed_token) do
-        instance_double(Html2rss::Web::FeedToken, username: 'admin', url:, strategy: 'default', selectors: nil)
+        instance_double(Html2rss::Web::FeedToken, username: 'admin', url:, strategy: nil, selectors: nil)
       end
       let(:feed_request) do
         Html2rss::Web::Feeds::Contracts::Request.new(
@@ -62,7 +76,7 @@
       it 'returns one config for both paths' do
         served = Html2rss::Web::Feeds::SourceResolver.call(feed_request).generator_input
 
-        expect(served).to eq(described_class.for_token(url:, strategy: feed_token.strategy))
+        expect(served).to eq(described_class.for_token(url:))
       end
 
       it 'returns one config when both paths carry the same selectors' do
@@ -70,7 +84,7 @@
         allow(feed_token).to receive(:selectors).and_return(selectors)
         served = Html2rss::Web::Feeds::SourceResolver.call(feed_request).generator_input
 
-        expect(served).to eq(described_class.for_token(url:, strategy: feed_token.strategy, selectors:))
+        expect(served).to eq(described_class.for_token(url:, selectors:))
       end
     end
   end

From 309d377729958f4cdec09f5ed8b8dd7fb75f7363 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Mon, 21 Sep 2026 18:11:22 +0200
Subject: [PATCH 078/108] fix(api): weight feed creation as a live fetch

Create runs a full extraction but was charged one slot, and studio 429 shape was a second hardcoded path list.
---
 app/web/request/rate_limiter.rb        | 23 +++++++++++----
 spec/html2rss/web/rate_limiter_spec.rb | 39 ++++++++++++++++++++++++++
 2 files changed, 56 insertions(+), 6 deletions(-)

diff --git a/app/web/request/rate_limiter.rb b/app/web/request/rate_limiter.rb
index 94bab2e9..4a665fe6 100644
--- a/app/web/request/rate_limiter.rb
+++ b/app/web/request/rate_limiter.rb
@@ -10,9 +10,12 @@ module Web
     # Rack middleware providing IP-based rate limiting with fiber-native tracking,
     # automated pruning, and standardized 429 error formatting.
     class RateLimiter
+      # Live-fetch weights. Create is +POST /api/v1/feeds+ because that route runs
+      # {Feeds::Service}. Studio paths that only validate stay at one slot.
       LIVE_FETCH_PATH_COSTS = {
-        '/api/v1/feeds/preview' => 5,
-        '/api/v1/feeds/suggest_selectors' => 5
+        'POST /api/v1/feeds' => 5,
+        'POST /api/v1/feeds/preview' => 5,
+        'POST /api/v1/feeds/suggest_selectors' => 5
       }.freeze
       private_constant :LIVE_FETCH_PATH_COSTS
 
@@ -29,6 +32,9 @@ def initialize
 
         # Records request time, prunes old timestamps, and checks if limit is exceeded.
         #
+        # Admission looks at the current size, then appends +cost+ timestamps.
+        # A budget of N can overrun by cost - 1.
+        #
         # @param now [Integer]
         # @param window_seconds [Integer]
         # @param max_requests [Integer]
@@ -88,7 +94,7 @@ def call(env)
           now,
           Flags.rate_limit_window_seconds,
           Flags.rate_limit_max_requests,
-          cost: request_cost(path)
+          cost: request_cost(request, path)
         )
 
         if limit_exceeded
@@ -113,16 +119,21 @@ def call(env)
 
       private
 
+      # @param request [Rack::Request]
       # @param path [String]
       # @return [Integer]
-      def request_cost(path)
-        LIVE_FETCH_PATH_COSTS.fetch(path, 1)
+      def request_cost(request, path)
+        LIVE_FETCH_PATH_COSTS.fetch("#{request.request_method} #{path}", 1)
       end
 
+      # Studio POST names come from {Routes::ApiV1::FeedRoutes::STUDIO_POSTS}.
+      #
       # @param path [String]
       # @return [Boolean]
       def studio_path?(path)
-        LIVE_FETCH_PATH_COSTS.key?(path) || path == '/api/v1/feeds/validate'
+        Routes::ApiV1::FeedRoutes::STUDIO_POSTS.each_key.any? do |name|
+          path == "/api/v1/feeds/#{name}"
+        end
       end
 
       # @param path [String]
diff --git a/spec/html2rss/web/rate_limiter_spec.rb b/spec/html2rss/web/rate_limiter_spec.rb
index 1e1b0177..fde24c37 100644
--- a/spec/html2rss/web/rate_limiter_spec.rb
+++ b/spec/html2rss/web/rate_limiter_spec.rb
@@ -53,6 +53,45 @@
     end
   end
 
+  it 'weights feed creation as a live fetch', :aggregate_failures do
+    allow(Html2rss::Web::Flags).to receive(:rate_limit_max_requests).and_return(10)
+
+    2.times do
+      expect(request_builder.post('/api/v1/feeds').status).to eq(200)
+    end
+
+    response = request_builder.post('/api/v1/feeds')
+    expect(response.status).to eq(429)
+    expect(response['Content-Type']).to eq('application/json')
+  end
+
+  it 'keeps a new studio POST API-shaped on 429', :aggregate_failures do
+    stub_const(
+      'Html2rss::Web::Routes::ApiV1::FeedRoutes::STUDIO_POSTS',
+      { 'future_tool' => Html2rss::Web::Api::V1::PreviewFeed }.freeze
+    )
+    allow(Html2rss::Web::Flags).to receive(:rate_limit_max_requests).and_return(1)
+    builder = Rack::MockRequest.new(described_class.new(inner_app))
+
+    expect(builder.post('/api/v1/feeds/future_tool').status).to eq(200)
+
+    response = builder.post('/api/v1/feeds/future_tool')
+    expect(response.status).to eq(429)
+    expect(response['Content-Type']).to eq('application/json')
+    expect(JSON.parse(response.body).dig('error', 'code')).to eq('TOO_MANY_REQUESTS')
+  end
+
+  it 'keeps a feed path outside the studio post set feed-shaped on 429', :aggregate_failures do
+    allow(Html2rss::Web::Flags).to receive(:rate_limit_max_requests).and_return(1)
+    builder = Rack::MockRequest.new(described_class.new(inner_app))
+
+    builder.get('/api/v1/feeds/not-a-studio-post')
+    response = builder.get('/api/v1/feeds/not-a-studio-post')
+
+    expect(response.status).to eq(429)
+    expect(response['Content-Type']).to eq(Html2rss::Web::Feeds::FormatNegotiation::TEXT_PLAIN_CONTENT_TYPE)
+  end
+
   it 'bypasses rate limiting for health check routes' do
     4.times do
       response = request_builder.get('/api/v1/health')

From 29f434ca8454ae4d1968f9ea089b526b08b09ef5 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Mon, 21 Sep 2026 18:14:09 +0200
Subject: [PATCH 079/108] refactor(api): share one bounded JSON body reader

Create and studio posts each enforced the body cap, and the studio reader reached into CreateFeed for the limit.
---
 app/web/api/v1/create_feed.rb                 | 35 +---------
 app/web/api/v1/json_body.rb                   | 65 +++++++++++++++++++
 app/web/api/v1/studio_request.rb              | 25 +------
 .../web/api/studio_auth_chain_spec.rb         |  2 +-
 spec/html2rss/web/api/v1/json_body_spec.rb    | 49 ++++++++++++++
 5 files changed, 120 insertions(+), 56 deletions(-)
 create mode 100644 app/web/api/v1/json_body.rb
 create mode 100644 spec/html2rss/web/api/v1/json_body_spec.rb

diff --git a/app/web/api/v1/create_feed.rb b/app/web/api/v1/create_feed.rb
index 4602f2d4..18649bb8 100644
--- a/app/web/api/v1/create_feed.rb
+++ b/app/web/api/v1/create_feed.rb
@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require 'json'
 require 'time'
 
 module Html2rss
@@ -9,9 +8,8 @@ module Api
       module V1
         ##
         # Creates stable feed records from authenticated API requests.
-        module CreateFeed # rubocop:disable Metrics/ModuleLength
+        module CreateFeed
           FEED_ATTRIBUTE_KEYS = %i[id name url feed_token public_url json_public_url created_at updated_at].freeze
-          MAX_BODY_BYTES = 64 * 1024
           ABSOLUTE_URL_REGEXP = %r{\A[a-z][a-z0-9+\-.]*://}i
           HOSTNAME_INPUT_REGEXP = %r{
             \A(localhost(?::\d+)?|(?:\d{1,3}\.){3}\d{1,3}(?::\d+)?|(?:[a-z0-9-]+\.)+[a-z]{2,}(?::\d+)?)
@@ -60,7 +58,7 @@ def require_account(request)
             end
 
             def build_create_params(request, account)
-              enforce_body_limit!(request)
+              JsonBody.enforce_limit!(request)
               params = request_params(request)
               url = validated_url(params['url'], account)
               name = params['name'].to_s.strip
@@ -68,37 +66,10 @@ def build_create_params(request, account)
               FeedMetadata::CreateParams.new(url:, name:)
             end
 
-            def enforce_body_limit!(request)
-              return unless request.content_length.to_i > MAX_BODY_BYTES
-
-              raise Html2rss::Web::BadRequestError, 'Payload too large'
-            end
-
             def request_params(request)
               return request.params unless json_request?(request)
 
-              request.GET.merge(parsed_json_body(request))
-            end
-
-            def parsed_json_body(request)
-              raw_body = read_limited_body(request)
-              return {} if raw_body.strip.empty?
-
-              parsed = JSON.parse(raw_body)
-              raise Html2rss::Web::BadRequestError, 'Invalid JSON payload' unless parsed.is_a?(Hash)
-
-              parsed
-            rescue JSON::ParserError
-              raise Html2rss::Web::BadRequestError, 'Invalid JSON payload'
-            end
-
-            def read_limited_body(request)
-              enforce_body_limit!(request)
-
-              request.body.read(MAX_BODY_BYTES + 1).to_s.tap do |raw_body|
-                request.body.rewind
-                raise Html2rss::Web::BadRequestError, 'Payload too large' if raw_body.bytesize > MAX_BODY_BYTES
-              end
+              request.GET.merge(JsonBody.object(request))
             end
 
             def json_request?(request)
diff --git a/app/web/api/v1/json_body.rb b/app/web/api/v1/json_body.rb
new file mode 100644
index 00000000..99805796
--- /dev/null
+++ b/app/web/api/v1/json_body.rb
@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Html2rss
+  module Web
+    module Api
+      module V1
+        ##
+        # Size-bounded JSON object reader for create and studio requests.
+        module JsonBody
+          MAX_BODY_BYTES = 64 * 1024
+
+          class << self
+            ##
+            # Parses the request body as a JSON object.
+            #
+            # An empty body is an empty object. A body over {MAX_BODY_BYTES} is rejected
+            # before it is parsed. The body is rewound so a later reader can see it.
+            #
+            # @param request [Rack::Request]
+            # @return [Hash]
+            # @raise [Html2rss::Web::BadRequestError] when the body is too large or not a JSON object
+            def object(request)
+              raw = read(request)
+              return {} if raw.strip.empty?
+
+              parsed = JSON.parse(raw)
+              raise BadRequestError, 'Invalid JSON payload' unless parsed.is_a?(Hash)
+
+              parsed
+            rescue JSON::ParserError
+              raise BadRequestError, 'Invalid JSON payload'
+            end
+
+            ##
+            # Rejects a declared content length over {MAX_BODY_BYTES} without reading the body.
+            #
+            # @param request [Rack::Request]
+            # @return [void]
+            # @raise [Html2rss::Web::BadRequestError] when Content-Length is over the cap
+            def enforce_limit!(request)
+              return unless request.content_length.to_i > MAX_BODY_BYTES
+
+              raise BadRequestError, 'Payload too large'
+            end
+
+            private
+
+            # @param request [Rack::Request]
+            # @return [String]
+            def read(request)
+              enforce_limit!(request)
+
+              request.body.read(MAX_BODY_BYTES + 1).to_s.tap do |raw|
+                request.body.rewind
+                raise BadRequestError, 'Payload too large' if raw.bytesize > MAX_BODY_BYTES
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end
diff --git a/app/web/api/v1/studio_request.rb b/app/web/api/v1/studio_request.rb
index 1068305d..9ffa5b75 100644
--- a/app/web/api/v1/studio_request.rb
+++ b/app/web/api/v1/studio_request.rb
@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'json'
-
 module Html2rss
   module Web
     module Api
@@ -59,16 +57,9 @@ def page_url(raw_url, account)
             #
             # @param request [Rack::Request]
             # @return [Hash]
+            # @see JsonBody.object
             def json_object(request)
-              raw = read_body(request)
-              return {} if raw.strip.empty?
-
-              parsed = JSON.parse(raw)
-              raise BadRequestError, 'Invalid JSON payload' unless parsed.is_a?(Hash)
-
-              parsed
-            rescue JSON::ParserError
-              raise BadRequestError, 'Invalid JSON payload'
+              JsonBody.object(request)
             end
 
             private
@@ -83,18 +74,6 @@ def require_allowed_url(stripped, account)
 
               url
             end
-
-            # @param request [Rack::Request]
-            # @return [String]
-            def read_body(request)
-              limit = CreateFeed::MAX_BODY_BYTES
-              raise BadRequestError, 'Payload too large' if request.content_length.to_i > limit
-
-              request.body.read(limit + 1).to_s.tap do |raw|
-                request.body.rewind
-                raise BadRequestError, 'Payload too large' if raw.bytesize > limit
-              end
-            end
           end
         end
       end
diff --git a/spec/html2rss/web/api/studio_auth_chain_spec.rb b/spec/html2rss/web/api/studio_auth_chain_spec.rb
index b6f1ccbc..a47918a1 100644
--- a/spec/html2rss/web/api/studio_auth_chain_spec.rb
+++ b/spec/html2rss/web/api/studio_auth_chain_spec.rb
@@ -159,7 +159,7 @@ def pack(document) = Base64.urlsafe_encode64(Zlib::Deflate.deflate(JSON.generate
         )
       )
 
-      expect(body.bytesize).to be > Html2rss::Web::Api::V1::CreateFeed::MAX_BODY_BYTES
+      expect(body.bytesize).to be > Html2rss::Web::Api::V1::JsonBody::MAX_BODY_BYTES
       expect(status).to eq(400)
       expect(input.bytes_read).to eq(0)
     end
diff --git a/spec/html2rss/web/api/v1/json_body_spec.rb b/spec/html2rss/web/api/v1/json_body_spec.rb
new file mode 100644
index 00000000..68bfe9e5
--- /dev/null
+++ b/spec/html2rss/web/api/v1/json_body_spec.rb
@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'stringio'
+
+RSpec.describe Html2rss::Web::Api::V1::JsonBody do
+  def request_for(body, content_length: body.bytesize)
+    env = Rack::MockRequest.env_for(
+      '/api/v1/feeds',
+      method: 'POST',
+      input: body,
+      'CONTENT_TYPE' => 'application/json',
+      'CONTENT_LENGTH' => content_length.to_s
+    )
+    Rack::Request.new(env)
+  end
+
+  it 'parses a JSON object and rewinds the body', :aggregate_failures do
+    request = request_for('{"url":"https://example.com"}')
+
+    expect(described_class.object(request)).to eq('url' => 'https://example.com')
+    expect(request.body.read).to eq('{"url":"https://example.com"}')
+  end
+
+  it 'treats an empty body as an empty object' do
+    expect(described_class.object(request_for(''))).to eq({})
+  end
+
+  it 'rejects a JSON array' do
+    expect { described_class.object(request_for('[1]')) }
+      .to raise_error(Html2rss::Web::BadRequestError, 'Invalid JSON payload')
+  end
+
+  it 'rejects a declared length over the cap without reading', :aggregate_failures do
+    body = StringIO.new('{"url":"https://example.com"}')
+    request = request_for(body, content_length: described_class::MAX_BODY_BYTES + 1)
+
+    expect { described_class.object(request) }
+      .to raise_error(Html2rss::Web::BadRequestError, 'Payload too large')
+    expect(body.pos).to eq(0)
+  end
+
+  it 'rejects a body longer than the cap when length is understated' do
+    raw = 'x' * (described_class::MAX_BODY_BYTES + 1)
+
+    expect { described_class.object(request_for(raw, content_length: 1)) }
+      .to raise_error(Html2rss::Web::BadRequestError, 'Payload too large')
+  end
+end

From bb773655e460529691c14415719bcfed995f265f Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Mon, 21 Sep 2026 18:15:20 +0200
Subject: [PATCH 080/108] refactor(api): own preview samples outside the
 handler

RSS-to-sample mapping lived in the preview handler, so the meadow shape had no module the contract could stamp from.
---
 app/web/api/v1/preview_feed.rb                |  99 +--------------
 app/web/api/v1/preview_samples.rb             | 118 ++++++++++++++++++
 .../web/api/v1/preview_samples_spec.rb        |  52 ++++++++
 3 files changed, 171 insertions(+), 98 deletions(-)
 create mode 100644 app/web/api/v1/preview_samples.rb
 create mode 100644 spec/html2rss/web/api/v1/preview_samples_spec.rb

diff --git a/app/web/api/v1/preview_feed.rb b/app/web/api/v1/preview_feed.rb
index 7dda2473..523a7510 100644
--- a/app/web/api/v1/preview_feed.rb
+++ b/app/web/api/v1/preview_feed.rb
@@ -1,8 +1,5 @@
 # frozen_string_literal: true
 
-require 'nokogiri'
-require 'rss'
-
 module Html2rss
   module Web
     module Api
@@ -14,9 +11,6 @@ module V1
         # {Html2rss::Test::Result} fields. Never forwards +#to_h+, which includes +rss:+.
         # A later preview of the same canonical URL is replayed by {PreviewPageCache}.
         module PreviewFeed
-          # Gem samples stay at three items. Authenticated meadow size is owned here.
-          SAMPLE_LIMIT = 10
-
           class << self
             ##
             # @param request [Rack::Request]
@@ -56,103 +50,12 @@ def refined(selectors)
             def preview_fields(result)
               {
                 item_count: result.item_count,
-                sample_items: sample_items_with_images(result),
+                sample_items: PreviewSamples.from_result(result),
                 quality_report: result.quality_report&.to_h,
                 failure_kind: result.failure_kind&.to_sym,
                 validation_issues: result.validation_issues&.map(&:to_h)
               }
             end
-
-            # RSS items when the document parsed; otherwise the gem samples. Never the RSS body.
-            #
-            # @param result [Html2rss::Test::Result]
-            # @return [Array<Hash>]
-            def sample_items_with_images(result)
-              from_rss = samples_from_rss(result.rss)
-              return from_rss unless from_rss.nil?
-
-              result.sample_items
-            end
-
-            # @param rss [String, nil]
-            # @return [Array<Hash>, nil] nil asks the caller to keep gem samples
-            def samples_from_rss(rss)
-              return unless rss.is_a?(String) && !rss.strip.empty?
-
-              items = RSS::Parser.parse(rss, false)&.items.to_a
-              return if items.empty?
-
-              items.first(SAMPLE_LIMIT).map { sample_from_item(it) }
-            rescue RSS::Error
-              nil
-            end
-
-            # @param item [RSS::Rss::Channel::Item]
-            # @return [Hash]
-            def sample_from_item(item)
-              sample = {
-                'title' => item.title.to_s.strip,
-                'url' => item_link(item),
-                'published_at' => published_at(item)
-              }
-              image = description_image_src(item) || image_enclosure_url(item)
-              image ? sample.merge('image' => image) : sample
-            end
-
-            # @param item [RSS::Rss::Channel::Item]
-            # @return [String]
-            def item_link(item)
-              link = item.link if item.respond_to?(:link)
-              link = item.url if link.to_s.strip.empty? && item.respond_to?(:url)
-              link.to_s.strip
-            end
-
-            # @param item [RSS::Rss::Channel::Item]
-            # @return [String, nil]
-            def published_at(item)
-              value = item.pubDate if item.respond_to?(:pubDate)
-              return if value.nil?
-              return value.utc.iso8601 if value.respond_to?(:utc)
-
-              text = value.to_s.strip
-              text.empty? ? nil : text
-            end
-
-            # First http(s) +<img src>+ in the item description. Article images are prepended there.
-            #
-            # @param item [RSS::Rss::Channel::Item]
-            # @return [String, nil]
-            def description_image_src(item)
-              html = item.description.to_s if item.respond_to?(:description)
-              return if html.nil? || html.empty?
-
-              node = Nokogiri::HTML.fragment(html).css('img').find { http_image_url(it['src']) }
-              http_image_url(node['src']) if node
-            end
-
-            # Image +enclosure+ only. Audio and other types are not preview images.
-            #
-            # @param item [RSS::Rss::Channel::Item]
-            # @return [String, nil]
-            def image_enclosure_url(item)
-              return unless item.respond_to?(:enclosure)
-
-              enclosure = item.enclosure
-              type = enclosure.respond_to?(:type) ? enclosure.type.to_s : ''
-              return unless type.downcase.start_with?('image/')
-
-              http_image_url(enclosure.url)
-            end
-
-            # @param value [String, nil]
-            # @return [String, nil]
-            def http_image_url(value)
-              url = value.to_s.strip
-              return unless url.start_with?('https://', 'http://')
-              return if url.match?(/[[:space:]"'<>]/)
-
-              url
-            end
           end
         end
       end
diff --git a/app/web/api/v1/preview_samples.rb b/app/web/api/v1/preview_samples.rb
new file mode 100644
index 00000000..992ed13a
--- /dev/null
+++ b/app/web/api/v1/preview_samples.rb
@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require 'nokogiri'
+require 'rss'
+
+module Html2rss
+  module Web
+    module Api
+      module V1
+        ##
+        # Maps a preview extraction into meadow rows.
+        #
+        # Gem samples stay at three items. The authenticated meadow cap is {SAMPLE_LIMIT}.
+        # Rows use {SAMPLE_KEYS}. An unusable RSS document keeps the gem samples.
+        module PreviewSamples
+          SAMPLE_LIMIT = 10
+          SAMPLE_KEYS = %w[title url published_at image].freeze
+
+          class << self
+            ##
+            # RSS items when the document parsed; otherwise the gem samples.
+            #
+            # @param result [Html2rss::Test::Result]
+            # @return [Array<Hash>]
+            def from_result(result)
+              from_rss = samples_from_rss(result.rss)
+              return from_rss unless from_rss.nil?
+
+              result.sample_items
+            end
+
+            private
+
+            # @param rss [String, nil]
+            # @return [Array<Hash>, nil] nil asks the caller to keep gem samples
+            def samples_from_rss(rss)
+              return unless rss.is_a?(String) && !rss.strip.empty?
+
+              items = RSS::Parser.parse(rss, false)&.items.to_a
+              return if items.empty?
+
+              items.first(SAMPLE_LIMIT).map { sample_from_item(it) }
+            rescue RSS::Error
+              nil
+            end
+
+            # @param item [RSS::Rss::Channel::Item]
+            # @return [Hash]
+            def sample_from_item(item)
+              sample = {
+                'title' => item.title.to_s.strip,
+                'url' => item_link(item),
+                'published_at' => published_at(item)
+              }
+              image = description_image_src(item) || image_enclosure_url(item)
+              image ? sample.merge('image' => image) : sample
+            end
+
+            # @param item [RSS::Rss::Channel::Item]
+            # @return [String]
+            def item_link(item)
+              link = item.link if item.respond_to?(:link)
+              link = item.url if link.to_s.strip.empty? && item.respond_to?(:url)
+              link.to_s.strip
+            end
+
+            # @param item [RSS::Rss::Channel::Item]
+            # @return [String, nil]
+            def published_at(item)
+              value = item.pubDate if item.respond_to?(:pubDate)
+              return if value.nil?
+              return value.utc.iso8601 if value.respond_to?(:utc)
+
+              text = value.to_s.strip
+              text.empty? ? nil : text
+            end
+
+            # First http(s) +<img src>+ in the item description. Article images are prepended there.
+            #
+            # @param item [RSS::Rss::Channel::Item]
+            # @return [String, nil]
+            def description_image_src(item)
+              html = item.description.to_s if item.respond_to?(:description)
+              return if html.nil? || html.empty?
+
+              node = Nokogiri::HTML.fragment(html).css('img').find { http_image_url(it['src']) }
+              http_image_url(node['src']) if node
+            end
+
+            # Image +enclosure+ only. Audio and other types are not preview images.
+            #
+            # @param item [RSS::Rss::Channel::Item]
+            # @return [String, nil]
+            def image_enclosure_url(item)
+              return unless item.respond_to?(:enclosure)
+
+              enclosure = item.enclosure
+              type = enclosure.respond_to?(:type) ? enclosure.type.to_s : ''
+              return unless type.downcase.start_with?('image/')
+
+              http_image_url(enclosure.url)
+            end
+
+            # @param value [String, nil]
+            # @return [String, nil]
+            def http_image_url(value)
+              url = value.to_s.strip
+              return unless url.start_with?('https://', 'http://')
+              return if url.match?(/[[:space:]"'<>]/)
+
+              url
+            end
+          end
+        end
+      end
+    end
+  end
+end
diff --git a/spec/html2rss/web/api/v1/preview_samples_spec.rb b/spec/html2rss/web/api/v1/preview_samples_spec.rb
new file mode 100644
index 00000000..9eb0db4a
--- /dev/null
+++ b/spec/html2rss/web/api/v1/preview_samples_spec.rb
@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Html2rss::Web::Api::V1::PreviewSamples do
+  def preview_result(rss:, sample_items: [])
+    Struct.new(:rss, :sample_items).new(rss, sample_items)
+  end
+
+  def rss_item(index, extra = '')
+    %(<item><title>Item #{index}</title><link>https://example.com/#{index}</link>#{extra}</item>)
+  end
+
+  def rss_document(items)
+    %(<rss version="2.0"><channel><title>t</title>#{items}</channel></rss>)
+  end
+
+  def image_rss
+    items = [
+      rss_item(1, '<description>&lt;img src="https://cdn.example/1.jpg"&gt;</description>'),
+      rss_item(2, '<description>&lt;img src="javascript:alert(1)"&gt;</description>'),
+      rss_item(3, '<enclosure url="data:image/png;base64,aaaa" type="image/png" length="1"/>'),
+      rss_item(4, '<enclosure url="http://cdn.example/4.jpg" type="image/jpeg" length="2"/>')
+    ]
+    rss_document(items.join)
+  end
+
+  it 'maps rss rows and keeps only safe http images', :aggregate_failures do
+    rows = described_class.from_result(preview_result(rss: image_rss))
+
+    expect(rows.map { it['image'] }).to eq(
+      ['https://cdn.example/1.jpg', nil, nil, 'http://cdn.example/4.jpg']
+    )
+    expect(rows[1]).not_to have_key('image')
+    expect(rows[0].keys - described_class::SAMPLE_KEYS).to be_empty
+  end
+
+  it 'caps mapped rows at the sample limit', :aggregate_failures do
+    items = (1..12).map { rss_item(it) }.join
+    rows = described_class.from_result(preview_result(rss: rss_document(items)))
+
+    expect(rows.length).to eq(described_class::SAMPLE_LIMIT)
+    expect(rows.last['title']).to eq('Item 10')
+  end
+
+  it 'keeps gem samples when the rss document cannot be parsed', :aggregate_failures do
+    gem_samples = [{ 'title' => 'A' }]
+
+    expect(described_class.from_result(preview_result(rss: '<not rss', sample_items: gem_samples))).to eq(gem_samples)
+    expect(described_class.from_result(preview_result(rss: nil, sample_items: gem_samples))).to eq(gem_samples)
+  end
+end

From 824362475b9c7d5dbba5f845ef9b103dd1f709e1 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Mon, 21 Sep 2026 18:19:19 +0200
Subject: [PATCH 081/108] fix(openapi): stamp studio schemas from runtime
 owners

The published selector document rejected gsub post-processors the server accepts, and candidate buckets were a second handwritten list.
---
 app/web/api/v1/suggest_selectors.rb           | 11 ++-
 public/openapi.yaml                           | 78 +++++++++++++++++-
 .../web}/openapi_runtime_contract_spec.rb     | 63 +++++++++++++-
 spec/support/openapi_studio_schemas.rb        | 82 +++++++++++++++----
 4 files changed, 208 insertions(+), 26 deletions(-)
 rename spec/{support => html2rss/web}/openapi_runtime_contract_spec.rb (63%)

diff --git a/app/web/api/v1/suggest_selectors.rb b/app/web/api/v1/suggest_selectors.rb
index f23a5bed..5b390adf 100644
--- a/app/web/api/v1/suggest_selectors.rb
+++ b/app/web/api/v1/suggest_selectors.rb
@@ -12,6 +12,7 @@ module V1
         module SuggestSelectors
           # Upper bound for the client-supplied items selector hint.
           MAX_ITEMS_SELECTOR_LENGTH = 256
+          BUCKET_NAMES = %i[items title link published].freeze
 
           class << self
             ##
@@ -54,12 +55,10 @@ def suggestion(captured)
             # @return [Hash{Symbol=>Array<Hash>}]
             def candidate_buckets(raw)
               buckets = raw.is_a?(Hash) ? raw : {}
-              {
-                items: item_entries(bucket(buckets, :items)),
-                title: field_entries(bucket(buckets, :title)),
-                link: field_entries(bucket(buckets, :link)),
-                published: field_entries(bucket(buckets, :published))
-              }
+              BUCKET_NAMES.to_h do |name|
+                entries = bucket(buckets, name)
+                [name, name == :items ? item_entries(entries) : field_entries(entries)]
+              end
             end
 
             # @param buckets [Hash]
diff --git a/public/openapi.yaml b/public/openapi.yaml
index 1915726b..c0a9121e 100644
--- a/public/openapi.yaml
+++ b/public/openapi.yaml
@@ -1220,7 +1220,6 @@ components:
           type: object
           required:
           - selector
-          - extractor
           additionalProperties: false
           properties:
             selector:
@@ -1229,11 +1228,35 @@ components:
               type: string
               enum:
               - text
+            post_process:
+              type: array
+              items:
+                type: object
+                required:
+                - name
+                additionalProperties: true
+                properties:
+                  name:
+                    type: string
+                    enum:
+                    - gsub
+                    - markdown_to_html
+                    - parse_time
+                    - parse_uri
+                    - sanitize_html
+                    - substring
+                    - template
+                  pattern:
+                    type: string
+                  replacement:
+                    oneOf:
+                    - type: string
+                    - type: object
+                      additionalProperties: true
         url:
           type: object
           required:
           - selector
-          - extractor
           additionalProperties: false
           properties:
             selector:
@@ -1242,11 +1265,35 @@ components:
               type: string
               enum:
               - href
+            post_process:
+              type: array
+              items:
+                type: object
+                required:
+                - name
+                additionalProperties: true
+                properties:
+                  name:
+                    type: string
+                    enum:
+                    - gsub
+                    - markdown_to_html
+                    - parse_time
+                    - parse_uri
+                    - sanitize_html
+                    - substring
+                    - template
+                  pattern:
+                    type: string
+                  replacement:
+                    oneOf:
+                    - type: string
+                    - type: object
+                      additionalProperties: true
         published_at:
           type: object
           required:
           - selector
-          - extractor
           additionalProperties: false
           properties:
             selector:
@@ -1255,6 +1302,31 @@ components:
               type: string
               enum:
               - text
+            post_process:
+              type: array
+              items:
+                type: object
+                required:
+                - name
+                additionalProperties: true
+                properties:
+                  name:
+                    type: string
+                    enum:
+                    - gsub
+                    - markdown_to_html
+                    - parse_time
+                    - parse_uri
+                    - sanitize_html
+                    - substring
+                    - template
+                  pattern:
+                    type: string
+                  replacement:
+                    oneOf:
+                    - type: string
+                    - type: object
+                      additionalProperties: true
     PreviewSampleItem:
       description: One preview meadow row returned by POST /feeds/preview.
       type: object
diff --git a/spec/support/openapi_runtime_contract_spec.rb b/spec/html2rss/web/openapi_runtime_contract_spec.rb
similarity index 63%
rename from spec/support/openapi_runtime_contract_spec.rb
rename to spec/html2rss/web/openapi_runtime_contract_spec.rb
index 4e506018..1f56a9d4 100644
--- a/spec/support/openapi_runtime_contract_spec.rb
+++ b/spec/html2rss/web/openapi_runtime_contract_spec.rb
@@ -47,6 +47,15 @@ def studio_hull_spec
                                 'properties' => { 'title' => { 'type' => 'string' } }
                               }
                             },
+                            'candidates' => {
+                              'type' => 'object',
+                              'properties' => {
+                                'items' => { 'type' => 'array' },
+                                'title' => { 'type' => 'array' },
+                                'link' => { 'type' => 'array' },
+                                'published' => { 'type' => 'array' }
+                              }
+                            },
                             'selectors' => {
                               'nullable' => true,
                               'type' => 'object',
@@ -82,7 +91,21 @@ def studio_hull_spec
     expect(document['additionalProperties']).to be(false)
 
     sample = spec.dig('components', 'schemas', 'PreviewSampleItem')
-    expect(sample['properties'].keys).to include('title', 'url', 'published_at', 'image')
+    expect(sample['properties'].keys).to eq(Html2rss::Web::Api::V1::PreviewSamples::SAMPLE_KEYS)
+    expect(sample['required']).to eq(%w[title])
+  end
+
+  it 'publishes gsub post-processors the server accepts', :aggregate_failures do
+    spec = studio_hull_spec
+    described_class.stamp(spec)
+
+    post_process = spec.dig(
+      'components', 'schemas', 'RefinedSelectorsDocument', 'properties', 'title', 'properties', 'post_process', 'items'
+    )
+    expect(post_process.dig('properties', 'name', 'enum')).to include('gsub')
+    expect(post_process['additionalProperties']).to be(true)
+    expect(spec.dig('components', 'schemas', 'RefinedSelectorsDocument', 'properties', 'title', 'required'))
+      .to eq(%w[selector])
   end
 
   it 'rewrites request selectors hulls to the stamped document ref' do
@@ -124,4 +147,42 @@ def studio_hull_spec
       'allOf' => [{ '$ref' => '#/components/schemas/RefinedSelectorsDocument' }]
     )
   end
+
+  it 'rewrites candidates hulls to SelectorCandidates' do
+    spec = studio_hull_spec
+    described_class.stamp(spec)
+
+    candidates = spec.dig(
+      'paths', '/feeds/preview', 'post', 'responses', '200', 'content', 'application/json',
+      'schema', 'properties', 'data', 'properties', 'candidates'
+    )
+    expect(candidates).to eq('$ref' => '#/components/schemas/SelectorCandidates')
+  end
+
+  it 'stamps issue codes from the config allowlist' do
+    spec = issue_hull_spec
+    described_class.stamp(spec)
+
+    code = spec.dig('components', 'schemas', 'ValidationIssue', 'properties', 'code')
+    expect(code['enum']).to eq(Html2rss::Config::CODES.map(&:to_s).sort)
+  end
+
+  it 'publishes RefinedSelectorKey from the allowlist', :aggregate_failures do
+    spec = studio_hull_spec
+    described_class.stamp(spec)
+
+    key = spec.dig('components', 'schemas', 'RefinedSelectorKey')
+    expect(key['enum']).to eq(Html2rss::Web::RefinedSelectors::ALLOWED_KEYS.map(&:to_s).sort)
+    expect(key['type']).to eq('string')
+  end
+
+  def issue_hull_spec
+    properties = %w[actual code expected message path].to_h { [it, { 'type' => 'string' }] }
+    {
+      'components' => {
+        'schemas' => { 'ValidationIssue' => { 'type' => 'object', 'properties' => properties } }
+      },
+      'paths' => {}
+    }
+  end
 end
diff --git a/spec/support/openapi_studio_schemas.rb b/spec/support/openapi_studio_schemas.rb
index 8ffc017e..cc8ed2e6 100644
--- a/spec/support/openapi_studio_schemas.rb
+++ b/spec/support/openapi_studio_schemas.rb
@@ -16,15 +16,61 @@ module OpenapiStudioSchemas # rubocop:disable Metrics/ModuleLength -- stamped st
   def refined_field(extractors)
     {
       'type' => 'object',
-      'required' => %w[selector extractor],
+      'required' => %w[selector],
       'additionalProperties' => false,
       'properties' => {
         'selector' => { 'type' => 'string' },
-        'extractor' => { 'type' => 'string', 'enum' => extractors }
+        'extractor' => { 'type' => 'string', 'enum' => extractors },
+        'post_process' => post_process_schema
       }
     }
   end
 
+  # Gsub and the other gem processors are accepted by {Html2rss::Web::RefinedSelectors}.
+  # The published item stays open so processor options are not a second allowlist.
+  #
+  # @return [Hash]
+  def post_process_schema
+    { 'type' => 'array', 'items' => post_process_item }
+  end
+
+  # Gsub and the other gem processors are accepted by {Html2rss::Web::RefinedSelectors}.
+  # The published item stays open so processor options are not a second allowlist.
+  #
+  # @return [Hash]
+  def post_process_item
+    {
+      'type' => 'object',
+      'required' => %w[name],
+      'additionalProperties' => true,
+      'properties' => post_process_properties
+    }
+  end
+
+  # @return [Hash]
+  def post_process_properties
+    {
+      'name' => { 'type' => 'string', 'enum' => post_processor_names },
+      'pattern' => { 'type' => 'string' },
+      'replacement' => replacement_schema
+    }
+  end
+
+  # @return [Hash]
+  def replacement_schema
+    {
+      'oneOf' => [
+        { 'type' => 'string' },
+        { 'type' => 'object', 'additionalProperties' => true }
+      ]
+    }
+  end
+
+  # @return [Array<String>]
+  def post_processor_names
+    Html2rss::Selectors::PostProcessors::NAME_TO_CLASS.keys.map(&:to_s).sort
+  end
+
   # @return [Hash]
   def refined_selectors_document
     {
@@ -71,12 +117,11 @@ def preview_sample_item
 
   # @return [Hash]
   def preview_sample_properties
-    {
-      'title' => { 'type' => 'string' },
-      'url' => { 'type' => 'string', 'nullable' => true },
-      'published_at' => { 'type' => 'string', 'nullable' => true },
-      'image' => { 'type' => 'string', 'nullable' => true }
-    }
+    Html2rss::Web::Api::V1::PreviewSamples::SAMPLE_KEYS.to_h do |key|
+      property = { 'type' => 'string' }
+      property['nullable'] = true unless key == 'title'
+      [key, property]
+    end
   end
 
   # @param schemas [Hash]
@@ -140,10 +185,11 @@ def selectors_document_hull?(schema)
 
   # @return [Hash]
   def selector_candidates
+    names = bucket_names
     {
       'description' => 'Ranked selector candidates. Empty buckets are a successful response.',
       'type' => 'object',
-      'required' => %w[items title link published],
+      'required' => names,
       'additionalProperties' => false,
       'properties' => candidate_bucket_properties
     }
@@ -151,12 +197,15 @@ def selector_candidates
 
   # @return [Hash]
   def candidate_bucket_properties
-    {
-      'items' => { 'type' => 'array', 'items' => ITEMS_CANDIDATE_REF.dup },
-      'title' => { 'type' => 'array', 'items' => FIELD_CANDIDATE_REF.dup },
-      'link' => { 'type' => 'array', 'items' => FIELD_CANDIDATE_REF.dup },
-      'published' => { 'type' => 'array', 'items' => FIELD_CANDIDATE_REF.dup }
-    }
+    bucket_names.to_h do |name|
+      ref = name == 'items' ? ITEMS_CANDIDATE_REF : FIELD_CANDIDATE_REF
+      [name, { 'type' => 'array', 'items' => ref.dup }]
+    end
+  end
+
+  # @return [Array<String>]
+  def bucket_names
+    Html2rss::Web::Api::V1::SuggestSelectors::BUCKET_NAMES.map(&:to_s)
   end
 
   # @return [Hash]
@@ -200,10 +249,11 @@ def rewrite_candidates_property(properties)
   def candidates_hull?(schema)
     return false unless schema.is_a?(Hash)
 
+    names = bucket_names
     properties = schema['properties']
     return false unless properties.is_a?(Hash)
 
-    %w[items title link published].all? { properties[it].is_a?(Hash) }
+    names.all? { properties[it].is_a?(Hash) }
   end
 
   # @param schema [Object]

From 84db64316236b6f49fbf8848a9d2eb31b1964631 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Mon, 21 Sep 2026 18:20:23 +0200
Subject: [PATCH 082/108] refactor(studio): keep live preview orthogonal to
 phase

Live preview was baked into every phase variant, so changing it rebuilt the whole state by hand.
---
 frontend/src/studio/useStudio.ts | 102 +++++++++++--------------------
 1 file changed, 34 insertions(+), 68 deletions(-)

diff --git a/frontend/src/studio/useStudio.ts b/frontend/src/studio/useStudio.ts
index 1428288c..eff9dbe1 100644
--- a/frontend/src/studio/useStudio.ts
+++ b/frontend/src/studio/useStudio.ts
@@ -27,11 +27,7 @@ import {
 export const STUDIO_VALIDATE_DELAY_MS = 300;
 export const STUDIO_PREVIEW_SETTLE_MS = 800;
 
-interface StudioDocument {
-  readonly draft: StudioDraft;
-  readonly yaml: string;
-  readonly live: LivePreview;
-}
+export type StudioPhase = 'editing' | 'validating' | 'invalid' | 'saving' | 'failed';
 
 export type LivePreview =
   | { readonly status: 'idle' }
@@ -39,12 +35,15 @@ export type LivePreview =
   | { readonly status: 'ready'; readonly sample: StudioPreview }
   | { readonly status: 'failed'; readonly message: string };
 
-export type StudioState =
-  | (StudioDocument & { readonly phase: 'editing'; readonly validated: boolean })
-  | (StudioDocument & { readonly phase: 'validating' })
-  | (StudioDocument & { readonly phase: 'invalid'; readonly issues: readonly StudioIssue[] })
-  | (StudioDocument & { readonly phase: 'saving' })
-  | (StudioDocument & { readonly phase: 'failed'; readonly message: string });
+export interface StudioState {
+  readonly phase: StudioPhase;
+  readonly draft: StudioDraft;
+  readonly yaml: string;
+  readonly live: LivePreview;
+  readonly validated: boolean;
+  readonly issues: readonly StudioIssue[];
+  readonly message: string;
+}
 
 interface UseStudioOptions {
   readonly url: string;
@@ -65,6 +64,8 @@ export function useStudio({
     yaml: '',
     validated: false,
     live: { status: 'idle' },
+    issues: [],
+    message: '',
   });
   const [suggestion, setSuggestion] = useState<StudioSuggestion>(EMPTY_STUDIO_SUGGESTION);
   const [documentRevision, setDocumentRevision] = useState(0);
@@ -127,12 +128,7 @@ export function useStudio({
   async function runValidate(requestId: number, signal: AbortSignal, revision: number) {
     const sentDraft = stateReference.current.draft;
     cancelPreview();
-    setState((previous) => ({
-      phase: 'validating',
-      draft: previous.draft,
-      yaml: previous.yaml,
-      live: previous.live,
-    }));
+    setState((previous) => ({ ...previous, phase: 'validating' }));
 
     try {
       const outcome = await validateStudioSelectors(token, url, sentDraft, signal);
@@ -141,9 +137,8 @@ export function useStudio({
     } catch (error) {
       if (isAbortError(error) || signal.aborted || requestIdReference.current !== requestId) return;
       setState((previous) => ({
+        ...previous,
         phase: 'failed',
-        draft: previous.draft,
-        yaml: previous.yaml,
         live: restoreHeld(previous.live),
         message: error instanceof StudioRequestError ? error.message : COPY.unableToReachServer,
       }));
@@ -156,6 +151,7 @@ export function useStudio({
 
     if (!outcome.valid) {
       setState((previous) => ({
+        ...previous,
         phase: 'invalid',
         draft,
         yaml,
@@ -166,11 +162,11 @@ export function useStudio({
     }
 
     setState((previous) => ({
+      ...previous,
       phase: 'editing',
       draft,
       yaml,
       validated: true,
-      live: previous.live,
     }));
     if (revision === 0 && url === initialUrlReference.current) return;
     schedulePreview();
@@ -179,9 +175,9 @@ export function useStudio({
   function editSelectors(update: (draft: StudioDraft) => StudioDraft) {
     cancelPreview();
     setState((previous) => ({
+      ...previous,
       phase: 'editing',
       draft: update(previous.draft),
-      yaml: previous.yaml,
       validated: false,
       live: refreshLive(previous.live),
     }));
@@ -213,25 +209,31 @@ export function useStudio({
     setState((previous) => {
       if (!(previous.phase === 'editing' && previous.validated)) return previous;
       if (previewRequestReference.current !== requestId) return previous;
-      return assignLive(previous, {
-        status: 'loading',
-        held: studioPreviewSample(previous.live),
-      });
+      return {
+        ...previous,
+        live: {
+          status: 'loading',
+          held: studioPreviewSample(previous.live),
+        },
+      };
     });
 
     try {
       const sample = await previewStudioFeed(token, url, stateReference.current.draft, controller.signal);
       if (controller.signal.aborted || previewRequestReference.current !== requestId) return;
       if (sample.failureKind === 'execution') {
-        setState((previous) => assignLive(previous, { status: 'failed', message: COPY.previewUnavailable }));
+        setState((previous) => ({
+          ...previous,
+          live: { status: 'failed', message: COPY.previewUnavailable },
+        }));
         return;
       }
-      setState((previous) => assignLive(previous, { status: 'ready', sample }));
+      setState((previous) => ({ ...previous, live: { status: 'ready', sample } }));
     } catch (error) {
       if (isAbortError(error) || controller.signal.aborted || previewRequestReference.current !== requestId)
         return;
       const message = error instanceof StudioRequestError ? error.message : COPY.unableToReachServer;
-      setState((previous) => assignLive(previous, { status: 'failed', message }));
+      setState((previous) => ({ ...previous, live: { status: 'failed', message } }));
     }
   }
 
@@ -258,10 +260,8 @@ export function useStudio({
     } catch (error) {
       if (isAbortError(error) || suggestRequestReference.current !== requestId) return;
       setState((previous) => ({
+        ...previous,
         phase: 'failed',
-        draft: previous.draft,
-        yaml: previous.yaml,
-        live: previous.live,
         message: error instanceof StudioRequestError ? error.message : COPY.unableToReachServer,
       }));
     }
@@ -291,25 +291,17 @@ export function useStudio({
   async function save(create: (selectors: RefinedSelectorsDocument) => Promise<void>) {
     const requestId = ++saveRequestReference.current;
     const current = stateReference.current;
-    setState({ phase: 'saving', draft: current.draft, yaml: current.yaml, live: current.live });
+    setState({ ...current, phase: 'saving' });
 
     try {
       await create(selectorsFromDraft(current.draft));
       if (saveRequestReference.current !== requestId) return;
-      setState({
-        phase: 'editing',
-        draft: current.draft,
-        yaml: current.yaml,
-        validated: true,
-        live: current.live,
-      });
+      setState({ ...current, phase: 'editing', validated: true });
     } catch (error) {
       if (saveRequestReference.current !== requestId) return;
       setState({
+        ...current,
         phase: 'failed',
-        draft: current.draft,
-        yaml: current.yaml,
-        live: current.live,
         message: failureMessage(error),
       });
     }
@@ -364,32 +356,6 @@ function adoptServerDraft(sent: StudioDraft, incoming: StudioDraft): StudioDraft
   };
 }
 
-function assignLive(state: StudioState, live: LivePreview): StudioState {
-  switch (state.phase) {
-    case 'editing': {
-      return {
-        phase: 'editing',
-        draft: state.draft,
-        yaml: state.yaml,
-        validated: state.validated,
-        live,
-      };
-    }
-    case 'validating': {
-      return { phase: 'validating', draft: state.draft, yaml: state.yaml, live };
-    }
-    case 'invalid': {
-      return { phase: 'invalid', draft: state.draft, yaml: state.yaml, issues: state.issues, live };
-    }
-    case 'saving': {
-      return { phase: 'saving', draft: state.draft, yaml: state.yaml, live };
-    }
-    case 'failed': {
-      return { phase: 'failed', draft: state.draft, yaml: state.yaml, message: state.message, live };
-    }
-  }
-}
-
 function failureMessage(error: unknown): string {
   if (isFeedCreationError(error)) return error.message;
   if (error instanceof Error && error.message.trim()) return error.message;

From 317d1541bc9d280283770dc941141537a84b34ed Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Mon, 21 Sep 2026 18:21:34 +0200
Subject: [PATCH 083/108] refactor(studio): drop unused suggestion and panel
 nonce

---
 frontend/src/__tests__/useStudio.test.ts | 22 ++++++++--------------
 frontend/src/components/ConfigStudio.tsx | 24 +++++++++---------------
 frontend/src/studio/useStudio.ts         | 19 -------------------
 3 files changed, 17 insertions(+), 48 deletions(-)

diff --git a/frontend/src/__tests__/useStudio.test.ts b/frontend/src/__tests__/useStudio.test.ts
index fe698a7e..32bee1ed 100644
--- a/frontend/src/__tests__/useStudio.test.ts
+++ b/frontend/src/__tests__/useStudio.test.ts
@@ -675,32 +675,26 @@ describe('useStudio', () => {
     const { result } = renderHook(() => useStudio({ url: pageUrl, token, validateDelayMs: 0 }));
     await advanceValidate(0);
 
-    let resolveStale: (() => void) | undefined;
-    const stale = new Promise<void>((resolve) => {
-      resolveStale = resolve;
-    });
-    let resolveCurrent: (() => void) | undefined;
-    const current = new Promise<void>((resolve) => {
-      resolveCurrent = resolve;
-    });
+    const stale = Promise.withResolvers<void>();
+    const current = Promise.withResolvers<void>();
 
     act(() => {
-      void result.current.save(() => stale);
+      void result.current.save(() => stale.promise);
     });
     act(() => {
-      void result.current.save(() => current);
+      void result.current.save(() => current.promise);
     });
     expect(result.current.state.phase).toBe('saving');
 
     await act(async () => {
-      resolveStale?.();
-      await stale;
+      stale.resolve();
+      await stale.promise;
     });
     expect(result.current.state.phase).toBe('saving');
 
     await act(async () => {
-      resolveCurrent?.();
-      await current;
+      current.resolve();
+      await current.promise;
     });
     expect(result.current.state.phase).toBe('editing');
     const state = result.current.state;
diff --git a/frontend/src/components/ConfigStudio.tsx b/frontend/src/components/ConfigStudio.tsx
index 0474b503..ca1540b4 100644
--- a/frontend/src/components/ConfigStudio.tsx
+++ b/frontend/src/components/ConfigStudio.tsx
@@ -29,11 +29,6 @@ interface ConfigStudioProperties {
   readonly fallback?: ComponentChildren;
 }
 
-interface OpenPanel {
-  readonly field: StudioFieldId;
-  readonly nonce: number;
-}
-
 export function ConfigStudio(properties: ConfigStudioProperties) {
   const { url, token, onGenerate, fallback } = properties;
   const studio = useStudio({
@@ -42,12 +37,11 @@ export function ConfigStudio(properties: ConfigStudioProperties) {
   });
   const { state, suggestion } = studio;
   const issues = studioIssues(state);
-  const [panel, setPanel] = useState<OpenPanel | undefined>(undefined);
+  const [openField, setOpenField] = useState<StudioFieldId | undefined>(undefined);
   const [yamlOpen, setYamlOpen] = useState(false);
   const [copied, setCopied] = useState(false);
   const [showUnmapped, setShowUnmapped] = useState(false);
   const copyResetReference = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
-  const openField = panel?.field;
   const hiddenIssues = issues.filter((issue) => isHiddenIssue(issue, openField));
   const unmappedIssues = hiddenIssues.filter((issue) => issuePlace(issue.path).kind === 'hidden');
   const sample = studioPreviewSample(state.live);
@@ -55,9 +49,9 @@ export function ConfigStudio(properties: ConfigStudioProperties) {
   const isBusy = state.phase === 'validating' || state.phase === 'saving' || state.live.status === 'loading';
 
   useEffect(() => {
-    if (!panel) return;
+    if (!openField) return;
     focusElement('studio-field-selector');
-  }, [panel]);
+  }, [openField]);
 
   useEffect(() => {
     return () => {
@@ -66,7 +60,7 @@ export function ConfigStudio(properties: ConfigStudioProperties) {
   }, []);
 
   const openFieldPanel = (field: StudioFieldId) => {
-    setPanel((current) => (current?.field === field ? undefined : { field, nonce: Date.now() }));
+    setOpenField((current) => (current === field ? undefined : field));
   };
 
   const onHiddenIssues = () => {
@@ -147,12 +141,12 @@ export function ConfigStudio(properties: ConfigStudioProperties) {
         </button>
       ) : undefined}
 
-      {panel ? (
+      {openField ? (
         <FieldFixPanel
-          field={panel.field}
-          selector={state.draft.fields[panel.field].selector}
-          selectorMessages={fieldMessages(issues, panel.field)}
-          onSelector={(selector) => studio.setFieldSelector(panel.field, selector)}
+          field={openField}
+          selector={state.draft.fields[openField].selector}
+          selectorMessages={fieldMessages(issues, openField)}
+          onSelector={(selector) => studio.setFieldSelector(openField, selector)}
         />
       ) : undefined}
 
diff --git a/frontend/src/studio/useStudio.ts b/frontend/src/studio/useStudio.ts
index eff9dbe1..42710730 100644
--- a/frontend/src/studio/useStudio.ts
+++ b/frontend/src/studio/useStudio.ts
@@ -251,22 +251,6 @@ export function useStudio({
     editSelectors((draft) => withFieldSelector(draft, field, selector));
   };
 
-  async function requestSuggestion() {
-    const requestId = ++suggestRequestReference.current;
-    try {
-      const nextSuggestion = await suggestStudioSelectors(token, url, '');
-      if (suggestRequestReference.current !== requestId) return;
-      setSuggestion(nextSuggestion);
-    } catch (error) {
-      if (isAbortError(error) || suggestRequestReference.current !== requestId) return;
-      setState((previous) => ({
-        ...previous,
-        phase: 'failed',
-        message: error instanceof StudioRequestError ? error.message : COPY.unableToReachServer,
-      }));
-    }
-  }
-
   /** Toggle parts on the items string. Suggest never writes the draft; chips never write enhance. */
   function toggleItemsSelector(selector: string) {
     itemsTouchedReference.current = true;
@@ -315,9 +299,6 @@ export function useStudio({
     setFieldSelector,
     toggleItemsSelector,
     toggleFieldSelector,
-    requestSuggestion: () => {
-      void requestSuggestion();
-    },
     retryPreview,
     save,
   };

From acc33e74c02445f6e2b734bf59db83f1d1f4afd2 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Mon, 21 Sep 2026 18:23:06 +0200
Subject: [PATCH 084/108] fix(studio): name the field when a studio payload
 fails to parse

---
 frontend/src/__tests__/studioService.test.ts | 60 ++++++++++++++++++
 frontend/src/studio/studioService.ts         | 65 ++++++++++++--------
 2 files changed, 101 insertions(+), 24 deletions(-)
 create mode 100644 frontend/src/__tests__/studioService.test.ts

diff --git a/frontend/src/__tests__/studioService.test.ts b/frontend/src/__tests__/studioService.test.ts
new file mode 100644
index 00000000..7112bcf2
--- /dev/null
+++ b/frontend/src/__tests__/studioService.test.ts
@@ -0,0 +1,60 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { postPreviewFeed, postSuggestSelectors } from '../api/http/feeds';
+import { COPY } from '../journey/copy';
+import { emptyDraft } from '../studio/selectorDraft';
+import { previewStudioFeed, StudioRequestError, suggestStudioSelectors } from '../studio/studioService';
+
+vi.mock('../api/http/feeds', () => ({
+  postPreviewFeed: vi.fn(),
+  postSuggestSelectors: vi.fn(),
+  postValidateFeed: vi.fn(),
+}));
+
+const pageUrl = 'https://example.com/articles';
+const token = 'studio-token';
+
+function okEnvelope(data: unknown) {
+  return { ok: true, status: 200, body: { success: true, data } };
+}
+
+async function fieldOnFailure(work: Promise<unknown>): Promise<string | undefined> {
+  try {
+    await work;
+  } catch (error) {
+    expect(error).toBeInstanceOf(StudioRequestError);
+    if (!(error instanceof StudioRequestError)) return;
+    expect(error.message).toBe(COPY.unableToCompleteCreation);
+    return error.field;
+  }
+  expect.fail('expected a studio parse error');
+}
+
+describe('studio payload parsing', () => {
+  beforeEach(() => {
+    vi.mocked(postPreviewFeed).mockReset();
+    vi.mocked(postSuggestSelectors).mockReset();
+  });
+
+  it('names sample_items when the preview sample list is not an array', async () => {
+    vi.mocked(postPreviewFeed).mockResolvedValue(okEnvelope({ item_count: 0, sample_items: 'nope' }));
+
+    const field = await fieldOnFailure(previewStudioFeed(token, pageUrl, emptyDraft()));
+    expect(field).toBe('sample_items');
+  });
+
+  it('names sample_items when one sample is missing a title', async () => {
+    vi.mocked(postPreviewFeed).mockResolvedValue(
+      okEnvelope({ item_count: 1, sample_items: [{ url: 'https://example.com/a' }] })
+    );
+
+    const field = await fieldOnFailure(previewStudioFeed(token, pageUrl, emptyDraft()));
+    expect(field).toBe('sample_items');
+  });
+
+  it('names candidates when the suggestion buckets are missing', async () => {
+    vi.mocked(postSuggestSelectors).mockResolvedValue(okEnvelope({}));
+
+    const field = await fieldOnFailure(suggestStudioSelectors(token, pageUrl, 'article'));
+    expect(field).toBe('candidates');
+  });
+});
diff --git a/frontend/src/studio/studioService.ts b/frontend/src/studio/studioService.ts
index 8289ed31..59a6d114 100644
--- a/frontend/src/studio/studioService.ts
+++ b/frontend/src/studio/studioService.ts
@@ -70,13 +70,30 @@ export const EMPTY_STUDIO_SUGGESTION: StudioSuggestion = {
   published: [],
 };
 
+type StudioPayloadField =
+  | 'report'
+  | 'selectors'
+  | 'yaml'
+  | 'issues'
+  | 'sample_items'
+  | 'quality_report'
+  | 'failure_kind'
+  | 'candidates';
+
 export class StudioRequestError extends Error {
-  constructor(message: string) {
+  readonly field: StudioPayloadField | undefined;
+
+  constructor(message: string, field?: StudioPayloadField) {
     super(message);
     this.name = 'StudioRequestError';
+    this.field = field;
   }
 }
 
+function invalidStudioField(field: StudioPayloadField): never {
+  throw new StudioRequestError(COPY.unableToCompleteCreation, field);
+}
+
 function listedIssueCodes<const T extends readonly StudioIssueCode[]>(
   codes: [StudioIssueCode] extends [T[number]] ? T : never
 ): T {
@@ -148,7 +165,7 @@ function errorMessage(payload: unknown): string | undefined {
 
 function parseValidation(data: unknown): StudioValidationOutcome {
   if (!isPlainRecord(data) || !isPlainRecord(data.report) || typeof data.report.success !== 'boolean') {
-    throw new StudioRequestError(COPY.unableToCompleteCreation);
+    invalidStudioField('report');
   }
 
   return {
@@ -162,32 +179,32 @@ function parseValidation(data: unknown): StudioValidationOutcome {
 function parseSelectorsField(value: unknown): StudioDraft | undefined {
   if (isAbsent(value)) return;
   const draft = draftFromSelectors(value);
-  if (!draft) throw new StudioRequestError(COPY.unableToCompleteCreation);
+  if (!draft) invalidStudioField('selectors');
   return draft;
 }
 
 function parseYamlField(value: unknown): string | undefined {
   if (isAbsent(value)) return;
-  if (typeof value !== 'string') throw new StudioRequestError(COPY.unableToCompleteCreation);
+  if (typeof value !== 'string') invalidStudioField('yaml');
   return value;
 }
 
 function parseIssues(value: unknown): readonly StudioIssue[] {
-  if (!Array.isArray(value)) throw new StudioRequestError(COPY.unableToCompleteCreation);
+  if (!Array.isArray(value)) invalidStudioField('issues');
   return value.map((item) => parseIssue(item));
 }
 
 function parseIssue(value: unknown): StudioIssue {
   if (!isPlainRecord(value) || !Array.isArray(value.path) || typeof value.message !== 'string') {
-    throw new StudioRequestError(COPY.unableToCompleteCreation);
+    invalidStudioField('issues');
   }
 
   const code = knownIssueCode(value.code);
-  if (!code) throw new StudioRequestError(COPY.unableToCompleteCreation);
+  if (!code) invalidStudioField('issues');
 
   const path: string[] = [];
   for (const segment of value.path) {
-    if (typeof segment !== 'string') throw new StudioRequestError(COPY.unableToCompleteCreation);
+    if (typeof segment !== 'string') invalidStudioField('issues');
     path.push(segment);
   }
 
@@ -204,7 +221,7 @@ function knownIssueCode(value: unknown): StudioIssueCode | undefined {
 
 function parsePreview(data: unknown): StudioPreview {
   if (!isPlainRecord(data) || typeof data.item_count !== 'number' || !Array.isArray(data.sample_items)) {
-    throw new StudioRequestError(COPY.unableToCompleteCreation);
+    invalidStudioField('sample_items');
   }
 
   return {
@@ -217,22 +234,22 @@ function parsePreview(data: unknown): StudioPreview {
 
 function parseSampleItem(value: unknown): StudioSampleItem {
   if (!isPlainRecord(value) || typeof value.title !== 'string') {
-    throw new StudioRequestError(COPY.unableToCompleteCreation);
+    invalidStudioField('sample_items');
   }
 
   return {
     title: value.title,
-    url: optionalText(value.url),
-    publishedAt: optionalText(value.published_at),
+    url: optionalText(value.url, 'sample_items'),
+    publishedAt: optionalText(value.published_at, 'sample_items'),
     imageUrl: optionalImageUrl(value.image),
   };
 }
 
 function parseNativeFeed(value: unknown): string | undefined {
   if (isAbsent(value)) return;
-  if (!isPlainRecord(value)) throw new StudioRequestError(COPY.unableToCompleteCreation);
+  if (!isPlainRecord(value)) invalidStudioField('quality_report');
   if (!Object.hasOwn(value, 'native_feed') || isAbsent(value.native_feed)) return;
-  return optionalText(value.native_feed);
+  return optionalText(value.native_feed, 'quality_report');
 }
 
 function optionalImageUrl(value: unknown): string | undefined {
@@ -242,22 +259,22 @@ function optionalImageUrl(value: unknown): string | undefined {
   return;
 }
 
-function optionalText(value: unknown): string | undefined {
+function optionalText(value: unknown, field: StudioPayloadField): string | undefined {
   if (isAbsent(value)) return;
-  if (typeof value !== 'string') throw new StudioRequestError(COPY.unableToCompleteCreation);
+  if (typeof value !== 'string') invalidStudioField(field);
   const trimmed = value.trim();
   return trimmed.length > 0 ? trimmed : undefined;
 }
 
 function parseFailureKind(value: unknown): string | undefined {
   if (isAbsent(value)) return;
-  if (typeof value !== 'string') throw new StudioRequestError(COPY.unableToCompleteCreation);
+  if (typeof value !== 'string') invalidStudioField('failure_kind');
   return value.length > 0 ? value : undefined;
 }
 
 function parseSuggestion(data: unknown): StudioSuggestion {
   if (!isPlainRecord(data) || !isPlainRecord(data.candidates)) {
-    throw new StudioRequestError(COPY.unableToCompleteCreation);
+    invalidStudioField('candidates');
   }
 
   const buckets = data.candidates;
@@ -270,16 +287,16 @@ function parseSuggestion(data: unknown): StudioSuggestion {
 }
 
 function parseItemsCandidates(value: unknown): readonly StudioItemsCandidate[] {
-  if (!Array.isArray(value)) throw new StudioRequestError(COPY.unableToCompleteCreation);
+  if (!Array.isArray(value)) invalidStudioField('candidates');
   return value.map((entry) => parseItemsCandidate(entry));
 }
 
 function parseItemsCandidate(value: unknown): StudioItemsCandidate {
   if (!isPlainRecord(value) || typeof value.selector !== 'string') {
-    throw new StudioRequestError(COPY.unableToCompleteCreation);
+    invalidStudioField('candidates');
   }
   const selector = value.selector.trim();
-  if (selector.length === 0) throw new StudioRequestError(COPY.unableToCompleteCreation);
+  if (selector.length === 0) invalidStudioField('candidates');
   return {
     selector,
     enhance: value.enhance === true,
@@ -287,16 +304,16 @@ function parseItemsCandidate(value: unknown): StudioItemsCandidate {
 }
 
 function parseFieldCandidates(value: unknown): readonly StudioFieldCandidate[] {
-  if (!Array.isArray(value)) throw new StudioRequestError(COPY.unableToCompleteCreation);
+  if (!Array.isArray(value)) invalidStudioField('candidates');
   return value.map((entry) => parseFieldCandidate(entry));
 }
 
 function parseFieldCandidate(value: unknown): StudioFieldCandidate {
   if (!isPlainRecord(value) || typeof value.selector !== 'string') {
-    throw new StudioRequestError(COPY.unableToCompleteCreation);
+    invalidStudioField('candidates');
   }
   const selector = value.selector.trim();
-  if (selector.length === 0) throw new StudioRequestError(COPY.unableToCompleteCreation);
+  if (selector.length === 0) invalidStudioField('candidates');
   return { selector };
 }
 

From c0af444cb3291c6f2a09206b34fd0daa2057deeb Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Mon, 21 Sep 2026 18:24:57 +0200
Subject: [PATCH 085/108] fix(studio): expire cached preview pages and drop the
 temp file

---
 app/web/api/v1/preview_page_cache.rb | 49 ++++++++++++++++++++++++++--
 spec/html2rss/web/api/v1_spec.rb     | 36 ++++++++++++++++++++
 2 files changed, 82 insertions(+), 3 deletions(-)

diff --git a/app/web/api/v1/preview_page_cache.rb b/app/web/api/v1/preview_page_cache.rb
index 7aec8f22..961da29a 100644
--- a/app/web/api/v1/preview_page_cache.rb
+++ b/app/web/api/v1/preview_page_cache.rb
@@ -11,16 +11,19 @@ module V1
         #
         # Keyed by the canonical URL {PreviewFeed} already allowed. A different
         # URL replaces the slot after a successful fetch. Empty or failed bodies
-        # leave the stored page in place. The temp path is written here.
+        # leave the stored page in place. The same body keeps its temp file.
+        # A slot older than {TTL_SECONDS} is fetched again. Process exit
+        # removes the temp file.
         module PreviewPageCache
           Slot = Data.define(:url, :path)
           MUTEX = Mutex.new
+          TTL_SECONDS = 300
 
           class << self
             ##
             # @param url [String] canonical page URL
             # @param config [Hash{Symbol=>Object}] token config from {Feeds::GeneratorInput.for_token}
-            # @return [Hash{Symbol=>Object}] +config+, overlaid with +:local_file+ on a hit
+            # @return [Hash{Symbol=>Object}] +config+, overlaid with +:local_file+ on a fresh hit
             def replay(url, config)
               path = path_for(url)
               return config unless path
@@ -35,6 +38,7 @@ def replay(url, config)
             def store(url, result)
               body = storable_body(result)
               return unless body
+              return if keep_unchanged(url, body)
 
               publish(url, write_body(body))
             end
@@ -47,6 +51,8 @@ def clear!
               publish_slot(nil)
             end
 
+            at_exit { Html2rss::Web::Api::V1::PreviewPageCache.clear! }
+
             private
 
             # @param url [String]
@@ -54,10 +60,16 @@ def clear!
             def path_for(url)
               MUTEX.synchronize do
                 current = @slot
-                current.path if current&.url == url && File.file?(current.path)
+                current.path if current&.url == url && fresh?(current)
               end
             end
 
+            # @param slot [Slot]
+            # @return [Boolean]
+            def fresh?(slot)
+              File.file?(slot.path) && (Time.now - File.mtime(slot.path)) < TTL_SECONDS
+            end
+
             # @param config [Hash{Symbol=>Object}]
             # @param path [String]
             # @return [Hash{Symbol=>Object}]
@@ -80,6 +92,37 @@ def storable_body(result)
               body
             end
 
+            # Keeps the temp file when the stored page matches. A stale match
+            # is marked fresh again without a rewrite.
+            #
+            # @param url [String]
+            # @param body [String]
+            # @return [Boolean]
+            def keep_unchanged(url, body)
+              MUTEX.synchronize do
+                current = @slot
+                next false unless same_body?(current, url, body)
+
+                touch(current.path) unless fresh?(current)
+                true
+              end
+            end
+
+            # @param slot [Slot, nil]
+            # @param url [String]
+            # @param body [String]
+            # @return [Boolean]
+            def same_body?(slot, url, body)
+              slot&.url == url && File.file?(slot.path) && File.read(slot.path) == body
+            end
+
+            # @param path [String]
+            # @return [void]
+            def touch(path)
+              now = Time.now
+              File.utime(now, now, path)
+            end
+
             # @param url [String]
             # @param path [String]
             # @return [void]
diff --git a/spec/html2rss/web/api/v1_spec.rb b/spec/html2rss/web/api/v1_spec.rb
index cc2f9c42..5c990a59 100644
--- a/spec/html2rss/web/api/v1_spec.rb
+++ b/spec/html2rss/web/api/v1_spec.rb
@@ -1061,6 +1061,12 @@ def kept_page_result
       preview_result.with(response_body: '<html>kept</html>')
     end
 
+    def age_cached_page(path)
+      ttl = Html2rss::Web::Api::V1::PreviewPageCache::TTL_SECONDS
+      stale = Time.now - (ttl + 1)
+      File.utime(stale, stale, path)
+    end
+
     def rejected_page_results
       [
         kept_page_result,
@@ -1138,6 +1144,36 @@ def rejected_page_results
       expect(pages[1]).to eq('<html>kept</html>')
     end
 
+    it 'keeps one temp file when the stored page is unchanged', :aggregate_failures do
+      configs, pages = record_preview_results([kept_page_result, kept_page_result, kept_page_result])
+      3.times { post_preview(feed_url) }
+      paths = configs.filter_map { it.dig(:request, :local_file_path) }
+
+      expect(paths.uniq.size).to eq(1)
+      expect(pages.values_at(1, 2)).to eq(['<html>kept</html>', '<html>kept</html>'])
+    end
+
+    it 'fetches again after the cached page exceeds the ttl', :aggregate_failures do
+      configs, pages = record_preview_results([kept_page_result, kept_page_result, kept_page_result])
+      post_preview(feed_url)
+      post_preview(feed_url)
+      age_cached_page(configs[1].dig(:request, :local_file_path))
+      post_preview(feed_url)
+
+      expect(configs.map { it[:strategy] }).to eq([preview_strategy, :local_file, preview_strategy])
+      expect(pages[1]).to eq('<html>kept</html>')
+    end
+
+    it 'removes the temp file when the cache is cleared' do
+      configs, = record_preview_results([kept_page_result, kept_page_result])
+      post_preview(feed_url)
+      post_preview(feed_url)
+      path = configs[1].dig(:request, :local_file_path)
+      Html2rss::Web::Api::V1::PreviewPageCache.clear!
+
+      expect(File.file?(path)).to be(false)
+    end
+
     it 'keeps the stored page when a later body is empty or failed', :aggregate_failures do
       configs, pages = record_preview_results(rejected_page_results)
       post_preview(feed_url)

From b0447eba8461ad601b5c4120a8ae5f54a475e776 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Mon, 21 Sep 2026 18:25:51 +0200
Subject: [PATCH 086/108] docs(studio): record validate-echo ownership and
 preview limits

---
 CONTEXT.md                        | 2 +-
 app/web/api/v1/preview_samples.rb | 4 +++-
 docs/README.md                    | 2 +-
 frontend/src/feeds/feedParsers.ts | 1 +
 4 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/CONTEXT.md b/CONTEXT.md
index e4422583..ad6e3130 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -29,7 +29,7 @@ On create, `findCatalogEntries` matches the typed query against the catalog (URL
 Visiting create (including hashbang `#!/…` → `#/…`) bumps `createEntryKey` so the create surface remounts. Remount alone does not auto-submit; auto-submit requires `prefillUrl`.
 
 ### Config Studio
-Selector refinement for a token holder when studio is enabled. On a successful result, refinement is available on demand behind demoted **Refine selectors** on `#/result/:token` (collapsed by default; one meadow; live studio output replaces the result preview after an edit). The listing URL stays the created feed’s page; **Create another feed** starts a new listing. The visual builder and YAML are one document: validate exports `channel.url` plus selectors. Only `studioService` unwraps the studio envelope and maps ranked `candidates` (items / title / link / published) into domain suggestion buckets. Candidates never auto-apply. Chips add or remove selector parts on the authored comma-joined string; suggest does not write that string, and chips do not change Enhance. Field extractors remain fixed by the draft mapper. Save posts refined selectors through Creation IO and stays on the result view.
+Selector refinement for a token holder when studio is enabled. On a successful result, refinement is available on demand behind demoted **Refine selectors** on `#/result/:token` (collapsed by default; one meadow; live studio output replaces the result preview after an edit). The listing URL stays the created feed’s page; **Create another feed** starts a new listing. The visual builder and YAML are one document: validate exports `channel.url` plus selectors. A successful validate echo keeps the server’s items selector and enhance flag; the client keeps the field selectors it authored. Only `studioService` unwraps the studio envelope and maps ranked `candidates` (items / title / link / published) into domain suggestion buckets. Candidates never auto-apply. A suggestion that fails on open is silent and non-blocking: the panel stays editable without ranked choices. Chips add or remove selector parts on the authored comma-joined string; suggest does not write that string, and chips do not change Enhance. Field extractors remain fixed by the draft mapper. Save posts refined selectors through Creation IO and stays on the result view.
 
 ### Refined Selectors
 The allowlisted `selectors` document a token holder may attach on feed creation. Signed into the feed token and resolved on later serves. Not a full config: channel, headers, and strategy stay denied.
diff --git a/app/web/api/v1/preview_samples.rb b/app/web/api/v1/preview_samples.rb
index 992ed13a..e3fbee6e 100644
--- a/app/web/api/v1/preview_samples.rb
+++ b/app/web/api/v1/preview_samples.rb
@@ -10,7 +10,9 @@ module V1
         ##
         # Maps a preview extraction into meadow rows.
         #
-        # Gem samples stay at three items. The authenticated meadow cap is {SAMPLE_LIMIT}.
+        # Gem samples stay at three items. The authenticated meadow cap is {SAMPLE_LIMIT}
+        # (the same 10 the member JSON Feed preview uses in
+        # frontend/src/feeds/feedParsers.ts as PREVIEW_ITEM_LIMIT.member).
         # Rows use {SAMPLE_KEYS}. An unusable RSS document keeps the gem samples.
         module PreviewSamples
           SAMPLE_LIMIT = 10
diff --git a/docs/README.md b/docs/README.md
index 66ff8b62..c80238eb 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -214,7 +214,7 @@ Rules:
 
 `STUDIO_ENABLED=true` exposes the config refinement studio: `POST /api/v1/feeds/validate`, `POST /api/v1/feeds/preview`, and `POST /api/v1/feeds/suggest_selectors`. All three require a valid access token and return `403 Studio is disabled` when the flag is off. `POST /api/v1/feeds` returns the same `403` when the body carries a `selectors` object, because those selectors are studio output; a body without `selectors` stays the automatic path and keeps working with the flag off. `preview` and `suggest_selectors` additionally need `AUTO_SOURCE_ENABLED=true` because they fetch the caller's URL live, and they only accept URLs the caller's account is allowed to reach. Validate accepts the same page URL and, when it is present and allowed, exports it as `channel.url` beside the selectors. Authenticated preview samples are capped at 10 items and include only safe HTTP(S) image URLs. `GET /api/v1` advertises `instance.studio.enabled` so the SPA can hide selector controls when the flag is off. Refinement stays on `#/result/:token`. Leave the flag off in production unless you intend to let token holders run live extraction against arbitrary allowed URLs.
 
-Rate limiting still uses the shared `RATE_LIMIT_MAX_REQUESTS` budget over `RATE_LIMIT_WINDOW_SECONDS`, but each live-fetch studio request to `preview` or `suggest_selectors` consumes five request slots. This fixed weighting protects the more expensive HTTP/browser extraction paths without adding another deployment flag.
+Rate limiting still uses the shared `RATE_LIMIT_MAX_REQUESTS` budget over `RATE_LIMIT_WINDOW_SECONDS`. `POST /api/v1/feeds`, `POST /api/v1/feeds/preview`, and `POST /api/v1/feeds/suggest_selectors` each consume five request slots because they run live extraction. Validate stays at one slot. Admission counts the current size and then charges the cost, so a budget of N can overrun by cost − 1. A successful preview page is reused for five minutes (`PreviewPageCache::TTL_SECONDS`); an older page is fetched again. An unchanged body keeps its temp file, and process exit removes that file. This fixed weighting protects the more expensive HTTP/browser extraction paths without adding another deployment flag.
 
 ---
 
diff --git a/frontend/src/feeds/feedParsers.ts b/frontend/src/feeds/feedParsers.ts
index 5ffa238e..023b57ad 100644
--- a/frontend/src/feeds/feedParsers.ts
+++ b/frontend/src/feeds/feedParsers.ts
@@ -1,5 +1,6 @@
 import type { FeedPreviewItem, PreviewAudience } from '../api/contracts';
 
+// Member cap matches Html2rss::Web::Api::V1::PreviewSamples::SAMPLE_LIMIT.
 const PREVIEW_ITEM_LIMIT: Record<PreviewAudience, number> = {
   guest: 5,
   member: 10,

From 435d902cb51c72f05f8fd0398eec8cf872383c97 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Mon, 21 Sep 2026 18:26:09 +0200
Subject: [PATCH 087/108] chore(api): regenerate the studio OpenAPI client

---
 frontend/src/api/generated/types.gen.ts | 30 ++++++++++++++++++++++---
 1 file changed, 27 insertions(+), 3 deletions(-)

diff --git a/frontend/src/api/generated/types.gen.ts b/frontend/src/api/generated/types.gen.ts
index b4fc1ab6..49c35705 100644
--- a/frontend/src/api/generated/types.gen.ts
+++ b/frontend/src/api/generated/types.gen.ts
@@ -19,15 +19,39 @@ export type RefinedSelectorsDocument = {
   };
   title?: {
     selector: string;
-    extractor: 'text';
+    extractor?: 'text';
+    post_process?: Array<{
+      name: 'gsub' | 'markdown_to_html' | 'parse_time' | 'parse_uri' | 'sanitize_html' | 'substring' | 'template';
+      pattern?: string;
+      replacement?: string | {
+        [key: string]: unknown;
+      };
+      [key: string]: unknown;
+    }>;
   };
   url?: {
     selector: string;
-    extractor: 'href';
+    extractor?: 'href';
+    post_process?: Array<{
+      name: 'gsub' | 'markdown_to_html' | 'parse_time' | 'parse_uri' | 'sanitize_html' | 'substring' | 'template';
+      pattern?: string;
+      replacement?: string | {
+        [key: string]: unknown;
+      };
+      [key: string]: unknown;
+    }>;
   };
   published_at?: {
     selector: string;
-    extractor: 'text';
+    extractor?: 'text';
+    post_process?: Array<{
+      name: 'gsub' | 'markdown_to_html' | 'parse_time' | 'parse_uri' | 'sanitize_html' | 'substring' | 'template';
+      pattern?: string;
+      replacement?: string | {
+        [key: string]: unknown;
+      };
+      [key: string]: unknown;
+    }>;
   };
 };
 

From 7efe3a61874634dbfec66468d1961643b5709bcf Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Mon, 21 Sep 2026 19:24:35 +0200
Subject: [PATCH 088/108] fix(studio): keep result mounted when save advances
 the token

Studio re-generate committed the new feed before the hash updated, so
decideJourney flashed create and the unmatched-result effect bounced
to #/create. Follow in-memory result and keep the result panel mounted.
---
 frontend/e2e/smoke.spec.ts                   | 56 +++++++++++++++++---
 frontend/src/__tests__/decideJourney.test.ts |  4 +-
 frontend/src/__tests__/useFeedFlow.test.ts   | 46 ++++++++++++++++
 frontend/src/feed/decideJourney.ts           |  4 +-
 frontend/src/feed/useFeedFlow.ts             | 10 ++--
 5 files changed, 106 insertions(+), 14 deletions(-)

diff --git a/frontend/e2e/smoke.spec.ts b/frontend/e2e/smoke.spec.ts
index d67c7674..46223390 100644
--- a/frontend/e2e/smoke.spec.ts
+++ b/frontend/e2e/smoke.spec.ts
@@ -19,7 +19,7 @@ const API_FEEDS = /\/api\/v1\/feeds\/?$/;
 const API_VALIDATE = /\/api\/v1\/feeds\/validate\/?$/;
 const API_SUGGEST = /\/api\/v1\/feeds\/suggest_selectors\/?$/;
 const API_STUDIO_PREVIEW = /\/api\/v1\/feeds\/preview\/?$/;
-const API_JSON_PREVIEW = /\/api\/v1\/feeds\/generated-token\.json$/;
+const API_JSON_PREVIEW = /\/api\/v1\/feeds\/(?:generated-token|refined-token)\.json$/;
 
 const EXAMPLE_URL = 'https://example.com/articles';
 
@@ -66,10 +66,18 @@ async function stubStudioEndpoints(page: Page) {
   await fulfillJson(page, API_STUDIO_PREVIEW, studioPreviewSuccessBody());
 }
 
-async function createReadyResult(page: Page, options: MetadataOptions = {}) {
-  await stubSpaApi(page, { isCatalogEnabled: false, ...options });
-  if (options.isStudioEnabled !== false) await stubStudioEndpoints(page);
-  await fulfillJson(page, API_FEEDS, createdFeedBody(), 201);
+async function createReadyResult(
+  page: Page,
+  options: MetadataOptions & { stubFeedCreates?: (page: Page) => Promise<void> } = {}
+) {
+  const { stubFeedCreates, ...metadataOptions } = options;
+  await stubSpaApi(page, { isCatalogEnabled: false, ...metadataOptions });
+  if (metadataOptions.isStudioEnabled !== false) await stubStudioEndpoints(page);
+  if (stubFeedCreates) {
+    await stubFeedCreates(page);
+  } else {
+    await fulfillJson(page, API_FEEDS, createdFeedBody(), 201);
+  }
   await fulfillJson(page, API_JSON_PREVIEW, { items: [] }, 200, 'application/feed+json');
   await page.addInitScript(() => {
     localStorage.setItem('html2rss_access_token', 'token-123');
@@ -164,7 +172,7 @@ test.describe('frontend smoke', () => {
     await expect(page.getByLabel(COPY.urlLabel)).toBeFocused();
   });
 
-  test('shows result after successful feed creation and recovers unmatched result routes onto create', async ({
+  test('shows result after successful feed creation and realigns a stale result hash', async ({
     page,
   }) => {
     await stubSpaApi(page);
@@ -204,6 +212,17 @@ test.describe('frontend smoke', () => {
 
     await page.goto('/#/result/missing-token');
 
+    // In-memory listing wins over a stale hash; only an empty deep link clears to create.
+    await expect(page).toHaveURL(/\/#\/result\/generated-token$/);
+    await expect(page.locator('.result-shell')).toHaveAttribute('data-state', 'result');
+    await expect(page.getByText(COPY.feedReady)).toBeVisible();
+  });
+
+  test('recovers an empty result deep link onto create', async ({ page }) => {
+    await stubSpaApi(page, { isCatalogEnabled: false });
+
+    await page.goto('/#/result/missing-token');
+
     await expect(page).toHaveURL(/\/#\/create$/);
     await expect(page.getByLabel(COPY.urlLabel)).toBeVisible();
     await expect(page.getByText('Saved result unavailable')).toHaveCount(0);
@@ -226,7 +245,27 @@ test.describe('frontend smoke', () => {
     collectPosts(page, API_VALIDATE, validateRequests);
     collectPosts(page, API_STUDIO_PREVIEW, previewRequests);
 
-    await createReadyResult(page);
+    // First create keeps generated-token; studio save must mint a new token so the
+    // unmatched-result effect cannot hide a bounce-to-create regression.
+    let createCount = 0;
+    await createReadyResult(page, {
+      stubFeedCreates: async (readyPage) => {
+        await readyPage.route(API_FEEDS, async (route) => {
+          if (route.request().method() !== 'POST') {
+            await route.fallback();
+            return;
+          }
+          createCount += 1;
+          const body =
+            createCount === 1 ? createdFeedBody() : createdFeedBody({ feed_token: 'refined-token' });
+          await route.fulfill({
+            status: 201,
+            contentType: 'application/json',
+            body: JSON.stringify(body),
+          });
+        });
+      },
+    });
 
     await expect(page).toHaveURL(/\/#\/result\/generated-token$/);
     await expect(page.locator('.result-shell')).toHaveAttribute('data-state', 'result');
@@ -281,8 +320,9 @@ test.describe('frontend smoke', () => {
     await save.click();
     await refined;
     await expect(page.getByText(COPY.feedReady)).toBeVisible();
-    await expect(page).toHaveURL(/\/#\/result\/generated-token$/);
+    await expect(page).toHaveURL(/\/#\/result\/refined-token$/);
     await expect(page.locator('.result-shell')).toHaveAttribute('data-state', 'result');
+    await expect(page.getByRole('button', { name: COPY.saveAndGenerate })).toBeEnabled();
   });
 
   test('leaves a result when the hash is the retired refine route', async ({ page }) => {
diff --git a/frontend/src/__tests__/decideJourney.test.ts b/frontend/src/__tests__/decideJourney.test.ts
index 9e0ef9af..ab005203 100644
--- a/frontend/src/__tests__/decideJourney.test.ts
+++ b/frontend/src/__tests__/decideJourney.test.ts
@@ -43,7 +43,7 @@ describe('decideJourney', () => {
     });
   });
 
-  it('does not treat a mismatched or missing result as the result kind', () => {
+  it('keeps the result panel when the in-memory token leads the hash', () => {
     expect(
       decideJourney({
         feedFieldErrors: emptyErrors,
@@ -65,7 +65,7 @@ describe('decideJourney', () => {
           warnings: [],
         },
       })
-    ).toEqual({ kind: 'create' });
+    ).toMatchObject({ kind: 'result', feed: { feed_token: 'other-token' } });
 
     expect(
       decideJourney({
diff --git a/frontend/src/__tests__/useFeedFlow.test.ts b/frontend/src/__tests__/useFeedFlow.test.ts
index b9e35a78..46485725 100644
--- a/frontend/src/__tests__/useFeedFlow.test.ts
+++ b/frontend/src/__tests__/useFeedFlow.test.ts
@@ -258,6 +258,52 @@ describe('useFeedFlow', () => {
     expect(result.current.creationError).toBeUndefined();
   });
 
+  it('aligns the result hash with an in-memory feed when studio generate advances the token', async () => {
+    const refinedFeed = {
+      ...mockFeed,
+      feed_token: 'feed-token-2',
+      public_url: '/api/v1/feeds/feed-token-2',
+      json_public_url: '/api/v1/feeds/feed-token-2.json',
+    };
+
+    fetchMock
+      .mockResolvedValueOnce(Response.json({ success: true, data: { feed: mockFeed } }))
+      .mockResolvedValueOnce(Response.json({ items: [] }))
+      .mockResolvedValueOnce(Response.json({ success: true, data: { feed: refinedFeed } }))
+      .mockResolvedValueOnce(Response.json({ items: [] }));
+
+    const { result, rerender } = renderHook(
+      ({ route }) =>
+        useFeedFlow(
+          feedFlowProperties({
+            route,
+            token: 'access-token',
+            mayCreate: () => 'proceed',
+          })
+        ),
+      { initialProps: { route: { kind: 'create' as const } } }
+    );
+
+    act(() => {
+      result.current.onFeedFieldChange('url', 'https://example.com/articles');
+    });
+    await act(async () => {
+      await result.current.onFeedSubmit({ preventDefault: vi.fn() } as any);
+    });
+
+    mockNavigate.mockClear();
+    rerender({ route: { kind: 'result', feedToken: 'feed-token-1' } });
+
+    await act(async () => {
+      await result.current.generateFromStudio({ items: { selector: 'article' } });
+    });
+
+    expect(mockNavigate).not.toHaveBeenCalledWith({ kind: 'create' }, expect.anything());
+    expect(mockNavigate).not.toHaveBeenCalledWith({ kind: 'create' });
+    expect(mockNavigate).toHaveBeenCalledWith({ kind: 'result', feedToken: 'feed-token-2' });
+    expect(result.current.result?.feed.feed_token).toBe('feed-token-2');
+  });
+
   it('remounts create on a later create-entry visit and clears creation chrome', async () => {
     await stubFeedCreationFailure();
 
diff --git a/frontend/src/feed/decideJourney.ts b/frontend/src/feed/decideJourney.ts
index 5c2fedff..d21ee7f7 100644
--- a/frontend/src/feed/decideJourney.ts
+++ b/frontend/src/feed/decideJourney.ts
@@ -45,7 +45,9 @@ export function decideJourney({
   tokenError: string;
   result?: CreatedFeedResult;
 }): AppViewModel {
-  if (route.kind === 'result' && result && result.feed.feed_token === route.feedToken) {
+  // Result route with in-memory feed: keep the panel mounted even when studio
+  // re-generate advances the token before the hash catches up.
+  if (route.kind === 'result' && result) {
     return {
       kind: 'result',
       feed: result.feed,
diff --git a/frontend/src/feed/useFeedFlow.ts b/frontend/src/feed/useFeedFlow.ts
index 45a796ea..080570f5 100644
--- a/frontend/src/feed/useFeedFlow.ts
+++ b/frontend/src/feed/useFeedFlow.ts
@@ -193,12 +193,16 @@ export function useFeedFlow({
     void attemptFeedCreation(token ?? '');
   }, [feedFormData.url, isLoading, mayCreate, navigate, route.kind, token]);
 
-  // Recover unmatched result routes onto a remounted create view.
+  // Keep the hash aligned with in-memory result; only bounce empty deep links to create.
   useEffect(() => {
     if (route.kind !== 'result') return;
 
-    const isMatched = Boolean(result && result.feed.feed_token === route.feedToken);
-    if (isMatched) return;
+    if (result) {
+      if (result.feed.feed_token === route.feedToken) return;
+      // Studio re-generate commits the new token before navigate runs; follow memory, do not clear.
+      navigate({ kind: 'result', feedToken: result.feed.feed_token }, { replace: true });
+      return;
+    }
 
     // Do not carry a prefill URL — that would re-trigger auto-submit and bounce back to result.
     navigate({ kind: 'create' }, { replace: true });

From 493022e7f02fc89c84a99e473e36fbcc8d4c3077 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Mon, 21 Sep 2026 19:26:48 +0200
Subject: [PATCH 089/108] style(e2e): format smoke.spec.ts for Prettier

ci-ready failed format:check on the post-save bounce e2e title wrapping.
---
 frontend/e2e/smoke.spec.ts | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/frontend/e2e/smoke.spec.ts b/frontend/e2e/smoke.spec.ts
index 46223390..ba9d8b2c 100644
--- a/frontend/e2e/smoke.spec.ts
+++ b/frontend/e2e/smoke.spec.ts
@@ -172,9 +172,7 @@ test.describe('frontend smoke', () => {
     await expect(page.getByLabel(COPY.urlLabel)).toBeFocused();
   });
 
-  test('shows result after successful feed creation and realigns a stale result hash', async ({
-    page,
-  }) => {
+  test('shows result after successful feed creation and realigns a stale result hash', async ({ page }) => {
     await stubSpaApi(page);
     await stubStudioEndpoints(page);
     await fulfillJson(page, API_FEEDS, createdFeedBody(), 201);

From ff5a9e21c69d7255d1683740b9132e2bd5da6b85 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Mon, 21 Sep 2026 23:28:37 +0200
Subject: [PATCH 090/108] fix(openapi): drop unused RefinedSelectorKey stamp

Nothing referenced the allowlist enum, so Spectral flagged it. Root key
enforcement stays on RefinedSelectors.
---
 frontend/src/api/generated/index.ts                | 2 +-
 frontend/src/api/generated/types.gen.ts            | 5 -----
 public/openapi.yaml                                | 5 -----
 spec/html2rss/web/openapi_runtime_contract_spec.rb | 9 ---------
 spec/support/openapi.rb                            | 9 ++-------
 5 files changed, 3 insertions(+), 27 deletions(-)

diff --git a/frontend/src/api/generated/index.ts b/frontend/src/api/generated/index.ts
index 351544af..f827d4dc 100644
--- a/frontend/src/api/generated/index.ts
+++ b/frontend/src/api/generated/index.ts
@@ -1,4 +1,4 @@
 // This file is auto-generated by @hey-api/openapi-ts
 
 export { createFeed, getApiMetadata, getConfigCatalog, getHealthStatus, getLivenessProbe, getReadinessProbe, listStrategies, type Options, optionsConfigCatalog, previewFeed, renderFeedByToken, suggestSelectors, validateFeedConfig } from './sdk.gen';
-export type { ClientOptions, CreateFeedData, CreateFeedError, CreateFeedErrors, CreateFeedResponse, CreateFeedResponses, FieldSelectorCandidate, GetApiMetadataData, GetApiMetadataResponse, GetApiMetadataResponses, GetConfigCatalogData, GetConfigCatalogError, GetConfigCatalogErrors, GetConfigCatalogResponse, GetConfigCatalogResponses, GetHealthStatusData, GetHealthStatusError, GetHealthStatusErrors, GetHealthStatusResponse, GetHealthStatusResponses, GetLivenessProbeData, GetLivenessProbeResponse, GetLivenessProbeResponses, GetReadinessProbeData, GetReadinessProbeResponse, GetReadinessProbeResponses, ItemsSelectorCandidate, ListStrategiesData, ListStrategiesResponse, ListStrategiesResponses, OptionsConfigCatalogData, OptionsConfigCatalogResponse, OptionsConfigCatalogResponses, PreviewFeedData, PreviewFeedResponse, PreviewFeedResponses, PreviewSampleItem, RefinedSelectorKey, RefinedSelectorsDocument, RenderFeedByTokenData, RenderFeedByTokenError, RenderFeedByTokenErrors, RenderFeedByTokenResponse, RenderFeedByTokenResponses, SelectorCandidates, SuggestSelectorsData, SuggestSelectorsResponse, SuggestSelectorsResponses, ValidateFeedConfigData, ValidateFeedConfigError, ValidateFeedConfigErrors, ValidateFeedConfigResponse, ValidateFeedConfigResponses } from './types.gen';
+export type { ClientOptions, CreateFeedData, CreateFeedError, CreateFeedErrors, CreateFeedResponse, CreateFeedResponses, FieldSelectorCandidate, GetApiMetadataData, GetApiMetadataResponse, GetApiMetadataResponses, GetConfigCatalogData, GetConfigCatalogError, GetConfigCatalogErrors, GetConfigCatalogResponse, GetConfigCatalogResponses, GetHealthStatusData, GetHealthStatusError, GetHealthStatusErrors, GetHealthStatusResponse, GetHealthStatusResponses, GetLivenessProbeData, GetLivenessProbeResponse, GetLivenessProbeResponses, GetReadinessProbeData, GetReadinessProbeResponse, GetReadinessProbeResponses, ItemsSelectorCandidate, ListStrategiesData, ListStrategiesResponse, ListStrategiesResponses, OptionsConfigCatalogData, OptionsConfigCatalogResponse, OptionsConfigCatalogResponses, PreviewFeedData, PreviewFeedResponse, PreviewFeedResponses, PreviewSampleItem, RefinedSelectorsDocument, RenderFeedByTokenData, RenderFeedByTokenError, RenderFeedByTokenErrors, RenderFeedByTokenResponse, RenderFeedByTokenResponses, SelectorCandidates, SuggestSelectorsData, SuggestSelectorsResponse, SuggestSelectorsResponses, ValidateFeedConfigData, ValidateFeedConfigError, ValidateFeedConfigErrors, ValidateFeedConfigResponse, ValidateFeedConfigResponses } from './types.gen';
diff --git a/frontend/src/api/generated/types.gen.ts b/frontend/src/api/generated/types.gen.ts
index 49c35705..4373670c 100644
--- a/frontend/src/api/generated/types.gen.ts
+++ b/frontend/src/api/generated/types.gen.ts
@@ -4,11 +4,6 @@ export type ClientOptions = {
   baseUrl: 'https://api.html2rss.dev/api/v1' | 'http://127.0.0.1:4000/api/v1' | (string & {});
 };
 
-/**
- * Root keys a client-authored config fragment may contain.
- */
-export type RefinedSelectorKey = 'selectors';
-
 /**
  * Allowlisted selectors document for create, validate, and preview.
  */
diff --git a/public/openapi.yaml b/public/openapi.yaml
index c0a9121e..d9739ef1 100644
--- a/public/openapi.yaml
+++ b/public/openapi.yaml
@@ -1194,11 +1194,6 @@ components:
       scheme: bearer
       bearerFormat: JWT
   schemas:
-    RefinedSelectorKey:
-      description: Root keys a client-authored config fragment may contain.
-      enum:
-      - selectors
-      type: string
     RefinedSelectorsDocument:
       description: Allowlisted selectors document for create, validate, and preview.
       type: object
diff --git a/spec/html2rss/web/openapi_runtime_contract_spec.rb b/spec/html2rss/web/openapi_runtime_contract_spec.rb
index 1f56a9d4..db110743 100644
--- a/spec/html2rss/web/openapi_runtime_contract_spec.rb
+++ b/spec/html2rss/web/openapi_runtime_contract_spec.rb
@@ -167,15 +167,6 @@ def studio_hull_spec
     expect(code['enum']).to eq(Html2rss::Config::CODES.map(&:to_s).sort)
   end
 
-  it 'publishes RefinedSelectorKey from the allowlist', :aggregate_failures do
-    spec = studio_hull_spec
-    described_class.stamp(spec)
-
-    key = spec.dig('components', 'schemas', 'RefinedSelectorKey')
-    expect(key['enum']).to eq(Html2rss::Web::RefinedSelectors::ALLOWED_KEYS.map(&:to_s).sort)
-    expect(key['type']).to eq('string')
-  end
-
   def issue_hull_spec
     properties = %w[actual code expected message path].to_h { [it, { 'type' => 'string' }] }
     {
diff --git a/spec/support/openapi.rb b/spec/support/openapi.rb
index d6d96415..089dbd2b 100644
--- a/spec/support/openapi.rb
+++ b/spec/support/openapi.rb
@@ -9,7 +9,7 @@ module OpenapiRuntimeContract
   # @return [void]
   def stamp(spec)
     walk(spec) { |node| stamp_issue_schema(node) }
-    publish_allowed_keys(spec)
+    publish_studio_schemas(spec)
   end
 
   # @param node [Object]
@@ -67,13 +67,8 @@ def issue_schema?(properties)
 
   # @param spec [Hash]
   # @return [void]
-  def publish_allowed_keys(spec)
+  def publish_studio_schemas(spec)
     schemas = section(section(spec, :components), :schemas)
-    schemas['RefinedSelectorKey'] = {
-      'description' => 'Root keys a client-authored config fragment may contain.',
-      'enum' => Html2rss::Web::RefinedSelectors::ALLOWED_KEYS.map(&:to_s).sort,
-      'type' => 'string'
-    }
     OpenapiStudioSchemas.publish(schemas)
     OpenapiStudioSchemas.rewrite(spec)
   end

From bb1a47b48a5c317429d23a023c043b8516abedc9 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Mon, 21 Sep 2026 23:34:59 +0200
Subject: [PATCH 091/108] docs(plan): persist studio ceremony cut carrier

---
 .agents/plan/studio-ceremony-cut.md | 211 ++++++++++++++++++++++++++++
 1 file changed, 211 insertions(+)
 create mode 100644 .agents/plan/studio-ceremony-cut.md

diff --git a/.agents/plan/studio-ceremony-cut.md b/.agents/plan/studio-ceremony-cut.md
new file mode 100644
index 00000000..dd704656
--- /dev/null
+++ b/.agents/plan/studio-ceremony-cut.md
@@ -0,0 +1,211 @@
+# Implementation Plan: studio-ceremony-cut
+
+Intent: inline
+Circuit breaker approved: false
+
+## Product stance
+
+Recommendation: Build Now
+
+- Persona and path: Sam’s documented SPA path stays Create → token (if needed) → Result → Copy feed URL. This tranche does not add a journey step. It removes dead ceremony and cache polish left from the prior studio cleanup.
+- Interaction budget: zero new clicks. Suggest, preview settle, and first-edit skip stay as today.
+- Concept budget: zero new concepts. Selector refinement stays on `#/result/:token`. There is still no `#/refine` route.
+- Forced challenge: PreviewPageCache becomes process-lifetime (no TTL). Same URL still replays until replaced or process exit. That is simpler and matches how operators already reason about a single-slot cache.
+- Non-goals: no gem-schema OpenAPI generation; no dropping closed candidate/`RefinedSelectorsDocument` stamps; no dropping View-as-YAML; no merging `JsonBody` back; no collapsing field setters; no removing preview settle / first-edit skip.
+
+## Intent constraints
+
+- Earned seams stay: `RefinedSelectors`, `GeneratorInput`, `StudioRequest`/`JsonBody` ownership, `selectorDraft` part-toggle, `api/http` → service → hook layering, create weighting, save-phase recovery, result-mount follow.
+- SPA suggest sends `{ url }` only. Server `hint` + auth-chain oversized-hint coverage stay.
+- `PreviewPageCache` is process-lifetime single-slot tempfile + `at_exit`. No `TTL_SECONDS`, `fresh?`, or body-equality dedupe.
+- OpenAPI closed schemas stay. Only the duplicated `post_process_*` comment block is removed.
+- `STUDIO_PREVIEW_SETTLE_MS` and `revision === 0` first-preview skip stay.
+- View-as-YAML stays. `ConfigStudio` is not split into more files.
+- `StudioState`: `issues` only on `invalid`, `message` only on `failed`; `live` stays orthogonal/flat. Public hook return shape stays stable for tests.
+- User-facing parse failure stays `COPY.unableToCompleteCreation`. `StudioRequestError` field naming stays.
+
+## Classification and architecture
+
+- Classification: `surgical` (LOC/dead-state). Inherited from the approved plan. Do not relitigate.
+- Runtime route: `typescript-dev` and a small `ruby-dev` cache/spec touch. Not Rails.
+- Architecture branch: axioms ride-along; no architecture redesign.
+- Ownership decisions:
+  - `useStudio` drops dead `enhanceTouchedReference` / `itemsTouchedReference`.
+  - `studioService` / `api/http/feeds` drop SPA `itemsSelector`; suggest body is `{ url }`.
+  - `studioService` owns local parse helpers; no new deps.
+  - `PreviewPageCache` owns process-lifetime slot + tempfile; no TTL/dedupe.
+  - `OpenapiStudioSchemas` drops duplicated comment only.
+  - `useStudio` phase-discriminates `issues`/`message`; `live` remains flat.
+
+## Acceptance
+
+- Given a suggest call from the SPA, when it posts, then the body is `{ url }` only.
+- Given a preview of the same URL twice, when the slot still holds that URL and the file exists, then the second call replays without refetch. Given process exit, when the slot still exists, then the temp file is removed. There is no TTL-based refetch.
+- Given `StudioState` phase `invalid`, when readers ask for issues, then `issues` is present. Given phase `failed`, when readers ask for the message, then `message` is present. Given other phases, those fields are absent.
+- Given a malformed studio payload, when parsing fails, then the thrown error names the field and the message stays `COPY.unableToCompleteCreation`.
+- Given the OpenAPI studio schemas file, when the duplicated `post_process_item` comment is removed, then generation and the runtime contract still pass.
+
+## Shared files
+
+These paths appear in more than one phase because each phase changes a different fact:
+
+- `frontend/src/studio/useStudio.ts` — Phase 02 deletes touched refs; Phase 06 phase-discriminates issues/message.
+- `frontend/src/studio/studioService.ts` — Phase 02 drops itemsSelector; Phase 03 compresses parsers.
+- `frontend/src/__tests__/useStudio.test.ts` — Phase 02 and Phase 06 adjust call sites/assertions.
+- `frontend/src/__tests__/studioService.test.ts` — Phase 02 and Phase 03 adjust call sites.
+
+## Conditional risks
+
+- Observability: N/A. No APM, tracing, or logging contract changes.
+- Security: authn/authz rules stay on `StudioRequest`. Suggest hint remains server-side; SPA stops sending `items_selector`. `spec/html2rss/web/api/studio_auth_chain_spec.rb` remains the security chain for oversized hint.
+- Pre-ship: Phase 07 runs `make ci-ready` inside the Dev Container. No push unless asked.
+- All `verification_gate` commands run inside the Dev Container. A host-only exit is not a pass.
+
+<!-- phase:start -->
+
+## Phase 01 — Persist carrier
+
+Write this carrier with phase DTOs (`target_files`, `read_context`, `verification_gate`, `commit_message`). Circuit breaker: false.
+
+target_files:
+
+- `.agents/plan/studio-ceremony-cut.md`
+
+read_context:
+
+- `/Users/gil/.cursor/plans/studio_ceremony_cut_aa8b5e77.plan.md`
+- `.agents/plan/studio-architecture-cleanup.md`
+
+verification_gate: `test -f .agents/plan/studio-ceremony-cut.md`
+commit_message: `docs(plan): persist studio ceremony cut carrier`
+
+<!-- phase:end -->
+
+<!-- phase:start -->
+
+## Phase 02 — Dead refs and suggest hint
+
+In `useStudio.ts`: delete `enhanceTouchedReference` / `itemsTouchedReference` and their writes. In `studioService.ts` + `api/http/feeds.ts`: drop the SPA `itemsSelector` argument; `postSuggestSelectors` sends `{ url }` only (OpenAPI already allows optional `items_selector`). Keep server `hint` + auth-chain oversized-hint test. Update unit test call sites.
+
+target_files:
+
+- `frontend/src/studio/useStudio.ts`
+- `frontend/src/studio/studioService.ts`
+- `frontend/src/api/http/feeds.ts`
+- `frontend/src/__tests__/useStudio.test.ts`
+- `frontend/src/__tests__/studioService.test.ts`
+
+read_context:
+
+- `frontend/src/components/ConfigStudio.tsx`
+- `spec/html2rss/web/api/studio_auth_chain_spec.rb`
+
+verification_gate: `make test-frontend-unit`
+commit_message: `refactor(studio): drop dead refs and SPA suggest hint`
+
+<!-- phase:end -->
+
+<!-- phase:start -->
+
+## Phase 03 — Compress studioService parsers
+
+Add small local helpers (`expectRecord` / `expectString` / `expectArray` or equivalent) in `studioService.ts` and rewrite the repetitive parse* functions to use them. Keep `StudioRequestError` field naming and user-facing `COPY.unableToCompleteCreation`. No new deps.
+
+target_files:
+
+- `frontend/src/studio/studioService.ts`
+- `frontend/src/__tests__/studioService.test.ts`
+
+read_context:
+
+- `frontend/src/journey/copy.ts`
+
+verification_gate: `make test-frontend-unit`
+commit_message: `refactor(studio): compress studioService parsers`
+
+<!-- phase:end -->
+
+<!-- phase:start -->
+
+## Phase 04 — Slim PreviewPageCache
+
+Remove TTL/fresh/dedupe/touch paths; `path_for` only checks URL match + file exists; `store` always writes a new tempfile when storable. Keep `clear!` + `at_exit`. Delete/rewrite TTL and “unchanged temp file” examples in `v1_spec.rb`; keep replay / URL-replace / empty-does-not-clobber coverage. Update TTL mention in docs if present (process-lifetime, not 300s).
+
+target_files:
+
+- `app/web/api/v1/preview_page_cache.rb`
+- `spec/html2rss/web/api/v1_spec.rb`
+- `docs/README.md`
+- `CONTEXT.md`
+
+read_context:
+
+- `app/web/api/v1/preview_feed.rb`
+
+verification_gate: `bundle exec rspec spec/html2rss/web/api/v1_spec.rb`
+commit_message: `refactor(studio): slim PreviewPageCache to process lifetime`
+
+<!-- phase:end -->
+
+<!-- phase:start -->
+
+## Phase 05 — OpenAPI comment dedupe
+
+Remove the duplicated comment on `post_process_item` in `openapi_studio_schemas.rb`. No YAML regen unless a comment somehow affects generation (it will not).
+
+target_files:
+
+- `spec/support/openapi_studio_schemas.rb`
+
+read_context:
+
+- `spec/html2rss/web/openapi_runtime_contract_spec.rb`
+
+verification_gate: `bundle exec rspec spec/html2rss/web/openapi_runtime_contract_spec.rb`
+commit_message: `chore(openapi): dedupe post_process schema comments`
+
+<!-- phase:end -->
+
+<!-- phase:start -->
+
+## Phase 06 — StudioState: issues/message only when needed
+
+Restore a phase-discriminated shape so `issues` exists only on `invalid` and `message` only on `failed` (keep `live` orthogonal/flat as today). Adjust `studioIssues` / `canSaveStudio` / `ConfigStudio` readers if needed. Keep public hook return shape stable for tests.
+
+target_files:
+
+- `frontend/src/studio/useStudio.ts`
+- `frontend/src/components/ConfigStudio.tsx`
+- `frontend/src/__tests__/useStudio.test.ts`
+- `frontend/src/__tests__/ConfigStudio.test.tsx`
+
+read_context:
+
+- `frontend/src/studio/studioService.ts`
+
+verification_gate: `make test-frontend-unit && make lint-js`
+commit_message: `refactor(studio): phase-discriminate issues and message`
+
+<!-- phase:end -->
+
+<!-- phase:start -->
+
+## Phase 07 — Final gate
+
+`make ci-ready` in the Dev Container. No push unless asked.
+
+target_files: []
+
+read_context:
+
+- `AGENTS.md`
+- `Makefile`
+
+verification_gate: `make ci-ready`
+commit_message: `chore(studio): record ceremony cut ci-ready`
+
+<!-- phase:end -->
+
+## Out of scope
+
+Gem-schema OpenAPI generation; dropping closed candidate/`RefinedSelectorsDocument` stamps; dropping YAML UI; merging `JsonBody` back; collapsing field setters into one component API; preview settle / first-edit skip removal.

From 3691f413882e527a54031b9a972475143e76cdd5 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Mon, 21 Sep 2026 23:35:58 +0200
Subject: [PATCH 092/108] refactor(studio): drop dead refs and SPA suggest hint

---
 frontend/src/__tests__/apiHttp.feeds.test.ts | 2 +-
 frontend/src/__tests__/studioService.test.ts | 2 +-
 frontend/src/__tests__/useStudio.test.ts     | 1 -
 frontend/src/api/http/feeds.ts               | 5 +----
 frontend/src/studio/studioService.ts         | 3 +--
 frontend/src/studio/useStudio.ts             | 7 +------
 6 files changed, 5 insertions(+), 15 deletions(-)

diff --git a/frontend/src/__tests__/apiHttp.feeds.test.ts b/frontend/src/__tests__/apiHttp.feeds.test.ts
index 56b9b8b6..355d1d85 100644
--- a/frontend/src/__tests__/apiHttp.feeds.test.ts
+++ b/frontend/src/__tests__/apiHttp.feeds.test.ts
@@ -75,7 +75,7 @@ describe('studio JSON writes', () => {
 
     await postValidateFeed('token-123', 'https://example.com', selectors);
     await postPreviewFeed('token-123', 'https://example.com', selectors);
-    await postSuggestSelectors('token-123', 'https://example.com', 'article');
+    await postSuggestSelectors('token-123', 'https://example.com');
 
     const paths = fetchMock.mock.calls.map((call) => {
       const input = call[0];
diff --git a/frontend/src/__tests__/studioService.test.ts b/frontend/src/__tests__/studioService.test.ts
index 7112bcf2..3903c05a 100644
--- a/frontend/src/__tests__/studioService.test.ts
+++ b/frontend/src/__tests__/studioService.test.ts
@@ -54,7 +54,7 @@ describe('studio payload parsing', () => {
   it('names candidates when the suggestion buckets are missing', async () => {
     vi.mocked(postSuggestSelectors).mockResolvedValue(okEnvelope({}));
 
-    const field = await fieldOnFailure(suggestStudioSelectors(token, pageUrl, 'article'));
+    const field = await fieldOnFailure(suggestStudioSelectors(token, pageUrl));
     expect(field).toBe('candidates');
   });
 });
diff --git a/frontend/src/__tests__/useStudio.test.ts b/frontend/src/__tests__/useStudio.test.ts
index 32bee1ed..5302944d 100644
--- a/frontend/src/__tests__/useStudio.test.ts
+++ b/frontend/src/__tests__/useStudio.test.ts
@@ -477,7 +477,6 @@ describe('useStudio', () => {
     if (!(suggestInput instanceof Request)) return;
     expect(JSON.parse(await suggestInput.clone().text())).toEqual({
       url: pageUrl,
-      items_selector: '',
     });
 
     await act(async () => {
diff --git a/frontend/src/api/http/feeds.ts b/frontend/src/api/http/feeds.ts
index c3426647..f3c29426 100644
--- a/frontend/src/api/http/feeds.ts
+++ b/frontend/src/api/http/feeds.ts
@@ -11,7 +11,6 @@ import { jsonBaseUrl, unwrap, type HttpEnvelope } from './client';
 
 type CreateFeedBody = NonNullable<CreateFeedData['body']>;
 type PreviewFeedBody = NonNullable<PreviewFeedData['body']>;
-type SuggestSelectorsBody = NonNullable<SuggestSelectorsData['body']>;
 type ValidateFeedBody = NonNullable<ValidateFeedConfigData['body']>;
 
 const FEED_WRITE_URL = {
@@ -84,9 +83,7 @@ export function postPreviewFeed(
 export function postSuggestSelectors(
   token: string,
   url: string,
-  itemsSelector: string,
   signal?: AbortSignal
 ): Promise<HttpEnvelope> {
-  const body: SuggestSelectorsBody = { url, items_selector: itemsSelector };
-  return jsonWrite(FEED_WRITE_URL.suggest, token, body, signal);
+  return jsonWrite(FEED_WRITE_URL.suggest, token, { url }, signal);
 }
diff --git a/frontend/src/studio/studioService.ts b/frontend/src/studio/studioService.ts
index 59a6d114..0e557292 100644
--- a/frontend/src/studio/studioService.ts
+++ b/frontend/src/studio/studioService.ts
@@ -131,10 +131,9 @@ export async function previewStudioFeed(
 export async function suggestStudioSelectors(
   token: string,
   url: string,
-  itemsSelector: string,
   signal?: AbortSignal
 ): Promise<StudioSuggestion> {
-  const data = await studioData(await postSuggestSelectors(token, url, itemsSelector, signal));
+  const data = await studioData(await postSuggestSelectors(token, url, signal));
   return parseSuggestion(data);
 }
 
diff --git a/frontend/src/studio/useStudio.ts b/frontend/src/studio/useStudio.ts
index 42710730..c49b74b6 100644
--- a/frontend/src/studio/useStudio.ts
+++ b/frontend/src/studio/useStudio.ts
@@ -78,8 +78,6 @@ export function useStudio({
   const saveRequestReference = useRef(0);
   const previewTimerReference = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
   const previewAbortReference = useRef<AbortController | undefined>(undefined);
-  const enhanceTouchedReference = useRef(false);
-  const itemsTouchedReference = useRef(false);
   const previewSettleReference = useRef(previewSettleMs);
   previewSettleReference.current = previewSettleMs;
   const initialUrlReference = useRef(url);
@@ -117,7 +115,7 @@ export function useStudio({
 
   async function loadSuggestion(requestId: number, signal: AbortSignal) {
     try {
-      const evidence = await suggestStudioSelectors(token, url, '', signal);
+      const evidence = await suggestStudioSelectors(token, url, signal);
       if (signal.aborted || suggestRequestReference.current !== requestId) return;
       setSuggestion(evidence);
     } catch (error) {
@@ -238,12 +236,10 @@ export function useStudio({
   }
 
   const setItemsSelector = (itemsSelector: string) => {
-    itemsTouchedReference.current = true;
     editSelectors((draft) => withItemsSelector(draft, itemsSelector));
   };
 
   const setEnhance = (isEnhanced: boolean) => {
-    enhanceTouchedReference.current = true;
     editSelectors((draft) => withEnhance(draft, isEnhanced));
   };
 
@@ -253,7 +249,6 @@ export function useStudio({
 
   /** Toggle parts on the items string. Suggest never writes the draft; chips never write enhance. */
   function toggleItemsSelector(selector: string) {
-    itemsTouchedReference.current = true;
     editSelectors((draft) => withItemsSelector(draft, toggleSelectorParts(draft.itemsSelector, selector)));
   }
 

From 388316745fafee628860ad43f1e9db0c0cb9f2e1 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Mon, 21 Sep 2026 23:36:39 +0200
Subject: [PATCH 093/108] refactor(studio): compress studioService parsers

---
 frontend/src/studio/studioService.ts | 117 +++++++++++++--------------
 1 file changed, 57 insertions(+), 60 deletions(-)

diff --git a/frontend/src/studio/studioService.ts b/frontend/src/studio/studioService.ts
index 0e557292..971dac72 100644
--- a/frontend/src/studio/studioService.ts
+++ b/frontend/src/studio/studioService.ts
@@ -94,6 +94,21 @@ function invalidStudioField(field: StudioPayloadField): never {
   throw new StudioRequestError(COPY.unableToCompleteCreation, field);
 }
 
+function expectRecord(value: unknown, field: StudioPayloadField): Record<string, unknown> {
+  if (!isPlainRecord(value)) invalidStudioField(field);
+  return value;
+}
+
+function expectString(value: unknown, field: StudioPayloadField): string {
+  if (typeof value !== 'string') invalidStudioField(field);
+  return value;
+}
+
+function expectArray(value: unknown, field: StudioPayloadField): readonly unknown[] {
+  if (!Array.isArray(value)) invalidStudioField(field);
+  return value;
+}
+
 function listedIssueCodes<const T extends readonly StudioIssueCode[]>(
   codes: [StudioIssueCode] extends [T[number]] ? T : never
 ): T {
@@ -163,15 +178,15 @@ function errorMessage(payload: unknown): string | undefined {
 }
 
 function parseValidation(data: unknown): StudioValidationOutcome {
-  if (!isPlainRecord(data) || !isPlainRecord(data.report) || typeof data.report.success !== 'boolean') {
-    invalidStudioField('report');
-  }
+  const root = expectRecord(data, 'report');
+  const report = expectRecord(root.report, 'report');
+  if (typeof report.success !== 'boolean') invalidStudioField('report');
 
   return {
-    valid: data.report.success,
-    issues: parseIssues(data.report.issues),
-    draft: parseSelectorsField(data.selectors),
-    yaml: parseYamlField(data.yaml),
+    valid: report.success,
+    issues: parseIssues(report.issues),
+    draft: parseSelectorsField(root.selectors),
+    yaml: parseYamlField(root.yaml),
   };
 }
 
@@ -184,30 +199,25 @@ function parseSelectorsField(value: unknown): StudioDraft | undefined {
 
 function parseYamlField(value: unknown): string | undefined {
   if (isAbsent(value)) return;
-  if (typeof value !== 'string') invalidStudioField('yaml');
-  return value;
+  return expectString(value, 'yaml');
 }
 
 function parseIssues(value: unknown): readonly StudioIssue[] {
-  if (!Array.isArray(value)) invalidStudioField('issues');
-  return value.map((item) => parseIssue(item));
+  return expectArray(value, 'issues').map((item) => parseIssue(item));
 }
 
 function parseIssue(value: unknown): StudioIssue {
-  if (!isPlainRecord(value) || !Array.isArray(value.path) || typeof value.message !== 'string') {
-    invalidStudioField('issues');
-  }
-
-  const code = knownIssueCode(value.code);
+  const record = expectRecord(value, 'issues');
+  const message = expectString(record.message, 'issues');
+  const code = knownIssueCode(record.code);
   if (!code) invalidStudioField('issues');
 
   const path: string[] = [];
-  for (const segment of value.path) {
-    if (typeof segment !== 'string') invalidStudioField('issues');
-    path.push(segment);
+  for (const segment of expectArray(record.path, 'issues')) {
+    path.push(expectString(segment, 'issues'));
   }
 
-  return { path, code, message: value.message };
+  return { path, code, message };
 }
 
 function knownIssueCode(value: unknown): StudioIssueCode | undefined {
@@ -219,36 +229,33 @@ function knownIssueCode(value: unknown): StudioIssueCode | undefined {
 }
 
 function parsePreview(data: unknown): StudioPreview {
-  if (!isPlainRecord(data) || typeof data.item_count !== 'number' || !Array.isArray(data.sample_items)) {
-    invalidStudioField('sample_items');
-  }
+  const root = expectRecord(data, 'sample_items');
+  if (typeof root.item_count !== 'number') invalidStudioField('sample_items');
+  const sampleItems = expectArray(root.sample_items, 'sample_items');
 
   return {
-    itemCount: data.item_count,
-    items: data.sample_items.map((item) => parseSampleItem(item)),
-    nativeFeedUrl: parseNativeFeed(data.quality_report),
-    failureKind: parseFailureKind(data.failure_kind),
+    itemCount: root.item_count,
+    items: sampleItems.map((item) => parseSampleItem(item)),
+    nativeFeedUrl: parseNativeFeed(root.quality_report),
+    failureKind: parseFailureKind(root.failure_kind),
   };
 }
 
 function parseSampleItem(value: unknown): StudioSampleItem {
-  if (!isPlainRecord(value) || typeof value.title !== 'string') {
-    invalidStudioField('sample_items');
-  }
-
+  const record = expectRecord(value, 'sample_items');
   return {
-    title: value.title,
-    url: optionalText(value.url, 'sample_items'),
-    publishedAt: optionalText(value.published_at, 'sample_items'),
-    imageUrl: optionalImageUrl(value.image),
+    title: expectString(record.title, 'sample_items'),
+    url: optionalText(record.url, 'sample_items'),
+    publishedAt: optionalText(record.published_at, 'sample_items'),
+    imageUrl: optionalImageUrl(record.image),
   };
 }
 
 function parseNativeFeed(value: unknown): string | undefined {
   if (isAbsent(value)) return;
-  if (!isPlainRecord(value)) invalidStudioField('quality_report');
-  if (!Object.hasOwn(value, 'native_feed') || isAbsent(value.native_feed)) return;
-  return optionalText(value.native_feed, 'quality_report');
+  const report = expectRecord(value, 'quality_report');
+  if (!Object.hasOwn(report, 'native_feed') || isAbsent(report.native_feed)) return;
+  return optionalText(report.native_feed, 'quality_report');
 }
 
 function optionalImageUrl(value: unknown): string | undefined {
@@ -260,23 +267,19 @@ function optionalImageUrl(value: unknown): string | undefined {
 
 function optionalText(value: unknown, field: StudioPayloadField): string | undefined {
   if (isAbsent(value)) return;
-  if (typeof value !== 'string') invalidStudioField(field);
-  const trimmed = value.trim();
+  const trimmed = expectString(value, field).trim();
   return trimmed.length > 0 ? trimmed : undefined;
 }
 
 function parseFailureKind(value: unknown): string | undefined {
   if (isAbsent(value)) return;
-  if (typeof value !== 'string') invalidStudioField('failure_kind');
-  return value.length > 0 ? value : undefined;
+  const text = expectString(value, 'failure_kind');
+  return text.length > 0 ? text : undefined;
 }
 
 function parseSuggestion(data: unknown): StudioSuggestion {
-  if (!isPlainRecord(data) || !isPlainRecord(data.candidates)) {
-    invalidStudioField('candidates');
-  }
-
-  const buckets = data.candidates;
+  const root = expectRecord(data, 'candidates');
+  const buckets = expectRecord(root.candidates, 'candidates');
   return {
     items: parseItemsCandidates(buckets.items),
     title: parseFieldCandidates(buckets.title),
@@ -286,32 +289,26 @@ function parseSuggestion(data: unknown): StudioSuggestion {
 }
 
 function parseItemsCandidates(value: unknown): readonly StudioItemsCandidate[] {
-  if (!Array.isArray(value)) invalidStudioField('candidates');
-  return value.map((entry) => parseItemsCandidate(entry));
+  return expectArray(value, 'candidates').map((entry) => parseItemsCandidate(entry));
 }
 
 function parseItemsCandidate(value: unknown): StudioItemsCandidate {
-  if (!isPlainRecord(value) || typeof value.selector !== 'string') {
-    invalidStudioField('candidates');
-  }
-  const selector = value.selector.trim();
+  const record = expectRecord(value, 'candidates');
+  const selector = expectString(record.selector, 'candidates').trim();
   if (selector.length === 0) invalidStudioField('candidates');
   return {
     selector,
-    enhance: value.enhance === true,
+    enhance: record.enhance === true,
   };
 }
 
 function parseFieldCandidates(value: unknown): readonly StudioFieldCandidate[] {
-  if (!Array.isArray(value)) invalidStudioField('candidates');
-  return value.map((entry) => parseFieldCandidate(entry));
+  return expectArray(value, 'candidates').map((entry) => parseFieldCandidate(entry));
 }
 
 function parseFieldCandidate(value: unknown): StudioFieldCandidate {
-  if (!isPlainRecord(value) || typeof value.selector !== 'string') {
-    invalidStudioField('candidates');
-  }
-  const selector = value.selector.trim();
+  const record = expectRecord(value, 'candidates');
+  const selector = expectString(record.selector, 'candidates').trim();
   if (selector.length === 0) invalidStudioField('candidates');
   return { selector };
 }

From f17fbf445225f5c5aa98e1a67887b6cb884f18f6 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Mon, 21 Sep 2026 23:37:13 +0200
Subject: [PATCH 094/108] refactor(studio): slim PreviewPageCache to process
 lifetime

---
 app/web/api/v1/preview_page_cache.rb | 48 +++-------------------------
 docs/README.md                       |  2 +-
 spec/html2rss/web/api/v1_spec.rb     | 26 ---------------
 3 files changed, 5 insertions(+), 71 deletions(-)

diff --git a/app/web/api/v1/preview_page_cache.rb b/app/web/api/v1/preview_page_cache.rb
index 961da29a..b473e315 100644
--- a/app/web/api/v1/preview_page_cache.rb
+++ b/app/web/api/v1/preview_page_cache.rb
@@ -11,19 +11,17 @@ module V1
         #
         # Keyed by the canonical URL {PreviewFeed} already allowed. A different
         # URL replaces the slot after a successful fetch. Empty or failed bodies
-        # leave the stored page in place. The same body keeps its temp file.
-        # A slot older than {TTL_SECONDS} is fetched again. Process exit
-        # removes the temp file.
+        # leave the stored page in place. The slot lasts for the process
+        # lifetime; process exit removes the temp file.
         module PreviewPageCache
           Slot = Data.define(:url, :path)
           MUTEX = Mutex.new
-          TTL_SECONDS = 300
 
           class << self
             ##
             # @param url [String] canonical page URL
             # @param config [Hash{Symbol=>Object}] token config from {Feeds::GeneratorInput.for_token}
-            # @return [Hash{Symbol=>Object}] +config+, overlaid with +:local_file+ on a fresh hit
+            # @return [Hash{Symbol=>Object}] +config+, overlaid with +:local_file+ on a hit
             def replay(url, config)
               path = path_for(url)
               return config unless path
@@ -38,7 +36,6 @@ def replay(url, config)
             def store(url, result)
               body = storable_body(result)
               return unless body
-              return if keep_unchanged(url, body)
 
               publish(url, write_body(body))
             end
@@ -60,16 +57,10 @@ def clear!
             def path_for(url)
               MUTEX.synchronize do
                 current = @slot
-                current.path if current&.url == url && fresh?(current)
+                current.path if current&.url == url && File.file?(current.path)
               end
             end
 
-            # @param slot [Slot]
-            # @return [Boolean]
-            def fresh?(slot)
-              File.file?(slot.path) && (Time.now - File.mtime(slot.path)) < TTL_SECONDS
-            end
-
             # @param config [Hash{Symbol=>Object}]
             # @param path [String]
             # @return [Hash{Symbol=>Object}]
@@ -92,37 +83,6 @@ def storable_body(result)
               body
             end
 
-            # Keeps the temp file when the stored page matches. A stale match
-            # is marked fresh again without a rewrite.
-            #
-            # @param url [String]
-            # @param body [String]
-            # @return [Boolean]
-            def keep_unchanged(url, body)
-              MUTEX.synchronize do
-                current = @slot
-                next false unless same_body?(current, url, body)
-
-                touch(current.path) unless fresh?(current)
-                true
-              end
-            end
-
-            # @param slot [Slot, nil]
-            # @param url [String]
-            # @param body [String]
-            # @return [Boolean]
-            def same_body?(slot, url, body)
-              slot&.url == url && File.file?(slot.path) && File.read(slot.path) == body
-            end
-
-            # @param path [String]
-            # @return [void]
-            def touch(path)
-              now = Time.now
-              File.utime(now, now, path)
-            end
-
             # @param url [String]
             # @param path [String]
             # @return [void]
diff --git a/docs/README.md b/docs/README.md
index c80238eb..a7e52e87 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -214,7 +214,7 @@ Rules:
 
 `STUDIO_ENABLED=true` exposes the config refinement studio: `POST /api/v1/feeds/validate`, `POST /api/v1/feeds/preview`, and `POST /api/v1/feeds/suggest_selectors`. All three require a valid access token and return `403 Studio is disabled` when the flag is off. `POST /api/v1/feeds` returns the same `403` when the body carries a `selectors` object, because those selectors are studio output; a body without `selectors` stays the automatic path and keeps working with the flag off. `preview` and `suggest_selectors` additionally need `AUTO_SOURCE_ENABLED=true` because they fetch the caller's URL live, and they only accept URLs the caller's account is allowed to reach. Validate accepts the same page URL and, when it is present and allowed, exports it as `channel.url` beside the selectors. Authenticated preview samples are capped at 10 items and include only safe HTTP(S) image URLs. `GET /api/v1` advertises `instance.studio.enabled` so the SPA can hide selector controls when the flag is off. Refinement stays on `#/result/:token`. Leave the flag off in production unless you intend to let token holders run live extraction against arbitrary allowed URLs.
 
-Rate limiting still uses the shared `RATE_LIMIT_MAX_REQUESTS` budget over `RATE_LIMIT_WINDOW_SECONDS`. `POST /api/v1/feeds`, `POST /api/v1/feeds/preview`, and `POST /api/v1/feeds/suggest_selectors` each consume five request slots because they run live extraction. Validate stays at one slot. Admission counts the current size and then charges the cost, so a budget of N can overrun by cost − 1. A successful preview page is reused for five minutes (`PreviewPageCache::TTL_SECONDS`); an older page is fetched again. An unchanged body keeps its temp file, and process exit removes that file. This fixed weighting protects the more expensive HTTP/browser extraction paths without adding another deployment flag.
+Rate limiting still uses the shared `RATE_LIMIT_MAX_REQUESTS` budget over `RATE_LIMIT_WINDOW_SECONDS`. `POST /api/v1/feeds`, `POST /api/v1/feeds/preview`, and `POST /api/v1/feeds/suggest_selectors` each consume five request slots because they run live extraction. Validate stays at one slot. Admission counts the current size and then charges the cost, so a budget of N can overrun by cost − 1. A successful preview page is kept for the process lifetime in `PreviewPageCache` and reused for the same URL until a different URL replaces the slot or the process exits (which removes the temp file). This fixed weighting protects the more expensive HTTP/browser extraction paths without adding another deployment flag.
 
 ---
 
diff --git a/spec/html2rss/web/api/v1_spec.rb b/spec/html2rss/web/api/v1_spec.rb
index 5c990a59..49b5d833 100644
--- a/spec/html2rss/web/api/v1_spec.rb
+++ b/spec/html2rss/web/api/v1_spec.rb
@@ -1061,12 +1061,6 @@ def kept_page_result
       preview_result.with(response_body: '<html>kept</html>')
     end
 
-    def age_cached_page(path)
-      ttl = Html2rss::Web::Api::V1::PreviewPageCache::TTL_SECONDS
-      stale = Time.now - (ttl + 1)
-      File.utime(stale, stale, path)
-    end
-
     def rejected_page_results
       [
         kept_page_result,
@@ -1144,26 +1138,6 @@ def rejected_page_results
       expect(pages[1]).to eq('<html>kept</html>')
     end
 
-    it 'keeps one temp file when the stored page is unchanged', :aggregate_failures do
-      configs, pages = record_preview_results([kept_page_result, kept_page_result, kept_page_result])
-      3.times { post_preview(feed_url) }
-      paths = configs.filter_map { it.dig(:request, :local_file_path) }
-
-      expect(paths.uniq.size).to eq(1)
-      expect(pages.values_at(1, 2)).to eq(['<html>kept</html>', '<html>kept</html>'])
-    end
-
-    it 'fetches again after the cached page exceeds the ttl', :aggregate_failures do
-      configs, pages = record_preview_results([kept_page_result, kept_page_result, kept_page_result])
-      post_preview(feed_url)
-      post_preview(feed_url)
-      age_cached_page(configs[1].dig(:request, :local_file_path))
-      post_preview(feed_url)
-
-      expect(configs.map { it[:strategy] }).to eq([preview_strategy, :local_file, preview_strategy])
-      expect(pages[1]).to eq('<html>kept</html>')
-    end
-
     it 'removes the temp file when the cache is cleared' do
       configs, = record_preview_results([kept_page_result, kept_page_result])
       post_preview(feed_url)

From b49b44256dc74640865722efa3250d88de5985b3 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Mon, 21 Sep 2026 23:37:22 +0200
Subject: [PATCH 095/108] chore(openapi): dedupe post_process schema comments

---
 spec/support/openapi_studio_schemas.rb | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/spec/support/openapi_studio_schemas.rb b/spec/support/openapi_studio_schemas.rb
index cc8ed2e6..a5b46cbf 100644
--- a/spec/support/openapi_studio_schemas.rb
+++ b/spec/support/openapi_studio_schemas.rb
@@ -34,9 +34,6 @@ def post_process_schema
     { 'type' => 'array', 'items' => post_process_item }
   end
 
-  # Gsub and the other gem processors are accepted by {Html2rss::Web::RefinedSelectors}.
-  # The published item stays open so processor options are not a second allowlist.
-  #
   # @return [Hash]
   def post_process_item
     {

From dac862777c6aea2a2b695dc24c98c632237c2327 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Mon, 21 Sep 2026 23:39:13 +0200
Subject: [PATCH 096/108] refactor(studio): phase-discriminate issues and
 message

---
 frontend/src/studio/studioService.ts |  5 +--
 frontend/src/studio/useStudio.ts     | 50 +++++++++++++++++-----------
 2 files changed, 31 insertions(+), 24 deletions(-)

diff --git a/frontend/src/studio/studioService.ts b/frontend/src/studio/studioService.ts
index 971dac72..5c819393 100644
--- a/frontend/src/studio/studioService.ts
+++ b/frontend/src/studio/studioService.ts
@@ -212,10 +212,7 @@ function parseIssue(value: unknown): StudioIssue {
   const code = knownIssueCode(record.code);
   if (!code) invalidStudioField('issues');
 
-  const path: string[] = [];
-  for (const segment of expectArray(record.path, 'issues')) {
-    path.push(expectString(segment, 'issues'));
-  }
+  const path = Array.from(expectArray(record.path, 'issues'), (segment) => expectString(segment, 'issues'));
 
   return { path, code, message };
 }
diff --git a/frontend/src/studio/useStudio.ts b/frontend/src/studio/useStudio.ts
index c49b74b6..bdfe7d6f 100644
--- a/frontend/src/studio/useStudio.ts
+++ b/frontend/src/studio/useStudio.ts
@@ -35,16 +35,18 @@ export type LivePreview =
   | { readonly status: 'ready'; readonly sample: StudioPreview }
   | { readonly status: 'failed'; readonly message: string };
 
-export interface StudioState {
-  readonly phase: StudioPhase;
+interface StudioCore {
   readonly draft: StudioDraft;
   readonly yaml: string;
   readonly live: LivePreview;
   readonly validated: boolean;
-  readonly issues: readonly StudioIssue[];
-  readonly message: string;
 }
 
+export type StudioState =
+  | (StudioCore & { readonly phase: 'editing' | 'validating' | 'saving' })
+  | (StudioCore & { readonly phase: 'invalid'; readonly issues: readonly StudioIssue[] })
+  | (StudioCore & { readonly phase: 'failed'; readonly message: string });
+
 interface UseStudioOptions {
   readonly url: string;
   readonly token: string;
@@ -64,8 +66,6 @@ export function useStudio({
     yaml: '',
     validated: false,
     live: { status: 'idle' },
-    issues: [],
-    message: '',
   });
   const [suggestion, setSuggestion] = useState<StudioSuggestion>(EMPTY_STUDIO_SUGGESTION);
   const [documentRevision, setDocumentRevision] = useState(0);
@@ -126,7 +126,7 @@ export function useStudio({
   async function runValidate(requestId: number, signal: AbortSignal, revision: number) {
     const sentDraft = stateReference.current.draft;
     cancelPreview();
-    setState((previous) => ({ ...previous, phase: 'validating' }));
+    setState((previous) => ({ ...coreOf(previous), phase: 'validating' }));
 
     try {
       const outcome = await validateStudioSelectors(token, url, sentDraft, signal);
@@ -135,7 +135,7 @@ export function useStudio({
     } catch (error) {
       if (isAbortError(error) || signal.aborted || requestIdReference.current !== requestId) return;
       setState((previous) => ({
-        ...previous,
+        ...coreOf(previous),
         phase: 'failed',
         live: restoreHeld(previous.live),
         message: error instanceof StudioRequestError ? error.message : COPY.unableToReachServer,
@@ -149,7 +149,7 @@ export function useStudio({
 
     if (!outcome.valid) {
       setState((previous) => ({
-        ...previous,
+        ...coreOf(previous),
         phase: 'invalid',
         draft,
         yaml,
@@ -160,7 +160,7 @@ export function useStudio({
     }
 
     setState((previous) => ({
-      ...previous,
+      ...coreOf(previous),
       phase: 'editing',
       draft,
       yaml,
@@ -173,7 +173,7 @@ export function useStudio({
   function editSelectors(update: (draft: StudioDraft) => StudioDraft) {
     cancelPreview();
     setState((previous) => ({
-      ...previous,
+      ...coreOf(previous),
       phase: 'editing',
       draft: update(previous.draft),
       validated: false,
@@ -220,18 +220,15 @@ export function useStudio({
       const sample = await previewStudioFeed(token, url, stateReference.current.draft, controller.signal);
       if (controller.signal.aborted || previewRequestReference.current !== requestId) return;
       if (sample.failureKind === 'execution') {
-        setState((previous) => ({
-          ...previous,
-          live: { status: 'failed', message: COPY.previewUnavailable },
-        }));
+        setState((previous) => withLive(previous, { status: 'failed', message: COPY.previewUnavailable }));
         return;
       }
-      setState((previous) => ({ ...previous, live: { status: 'ready', sample } }));
+      setState((previous) => withLive(previous, { status: 'ready', sample }));
     } catch (error) {
       if (isAbortError(error) || controller.signal.aborted || previewRequestReference.current !== requestId)
         return;
       const message = error instanceof StudioRequestError ? error.message : COPY.unableToReachServer;
-      setState((previous) => ({ ...previous, live: { status: 'failed', message } }));
+      setState((previous) => withLive(previous, { status: 'failed', message }));
     }
   }
 
@@ -270,16 +267,16 @@ export function useStudio({
   async function save(create: (selectors: RefinedSelectorsDocument) => Promise<void>) {
     const requestId = ++saveRequestReference.current;
     const current = stateReference.current;
-    setState({ ...current, phase: 'saving' });
+    setState({ ...coreOf(current), phase: 'saving' });
 
     try {
       await create(selectorsFromDraft(current.draft));
       if (saveRequestReference.current !== requestId) return;
-      setState({ ...current, phase: 'editing', validated: true });
+      setState({ ...coreOf(current), phase: 'editing', validated: true });
     } catch (error) {
       if (saveRequestReference.current !== requestId) return;
       setState({
-        ...current,
+        ...coreOf(current),
         phase: 'failed',
         message: failureMessage(error),
       });
@@ -314,6 +311,19 @@ export function studioPreviewSample(live: LivePreview): StudioPreview | undefine
   return undefined;
 }
 
+function coreOf(state: StudioState): StudioCore {
+  return {
+    draft: state.draft,
+    yaml: state.yaml,
+    live: state.live,
+    validated: state.validated,
+  };
+}
+
+function withLive(state: StudioState, live: LivePreview): StudioState {
+  return { ...state, live };
+}
+
 function refreshLive(live: LivePreview): LivePreview {
   return { status: 'loading', held: studioPreviewSample(live) };
 }

From 8a961ba13e9703eda64d5601137cd44d49e34235 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Mon, 21 Sep 2026 23:45:26 +0200
Subject: [PATCH 097/108] refactor(security): symbolize refined selectors via
 HashUtil

Reuse the gem owner for key normalization and keep deep_freeze + caller-string isolation.
---
 app/web/security/refined_selectors.rb | 21 ++++-----------------
 1 file changed, 4 insertions(+), 17 deletions(-)

diff --git a/app/web/security/refined_selectors.rb b/app/web/security/refined_selectors.rb
index 8faebb7c..bbef6350 100644
--- a/app/web/security/refined_selectors.rb
+++ b/app/web/security/refined_selectors.rb
@@ -43,7 +43,9 @@ def deep_freeze(value)
         case value
         in Hash then value.each_value { deep_freeze(it) }
         in Array then value.each { deep_freeze(it) }
-        in String then return value.freeze
+        # HashUtil reuses string references; dup so freezing the handoff cannot
+        # freeze the caller's mutable strings.
+        in String then return value.dup.freeze
         else return value
         end
         value.freeze
@@ -125,7 +127,7 @@ def build(hash, validate_shape:)
         def normalized_fragment(hash)
           raise BadRequestError, 'refined selectors must be an object' unless hash.is_a?(Hash)
 
-          symbolize(hash)
+          Html2rss::HashUtil.deep_symbolize_keys(hash, context: 'refined selectors')
         end
 
         # @param fragment [Hash{Symbol=>Object}]
@@ -165,21 +167,6 @@ def validate_shape!(selectors)
 
           raise SchemaInvalid, report
         end
-
-        # @param value [Object]
-        # @return [Object]
-        def symbolize(value)
-          case value
-          in Hash
-            value.to_h { |key, nested| [key.to_sym, symbolize(nested)] }
-          in Array
-            value.map { symbolize(it) }
-          in String
-            value.dup
-          else
-            value
-          end
-        end
       end
     end
   end

From fb1f2c2638c7f3ee3cf05a66dbcc0b6156110f6b Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Mon, 21 Sep 2026 23:45:29 +0200
Subject: [PATCH 098/108] docs(agents): arrest hand-grown OpenAPI studio stamps

Require a runtime or gem owner before expanding hand-stamped studio schemas.
---
 AGENTS.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 5d58c6fc..f34c83f0 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -92,6 +92,8 @@ Token-holder refinement of the selectors subtree, then generate via create.
 
 After handler or envelope changes: `make openapi` and `make ci-ready`.
 
+Do not expand hand-stamped studio schemas in `spec/support/openapi_studio_schemas.rb` without deriving from a runtime or gem owner. Full gem JSON Schema → OpenAPI stamp generation stays future work.
+
 ## Generated OpenAPI SPA transport
 
 The frontend JSON API is the generated Hey API client, not hand-written `fetch`.

From bc7081ef80210a86a687d07c7516a11e5a29a872 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Mon, 21 Sep 2026 23:56:57 +0200
Subject: [PATCH 099/108] test(frontend): serve JSON preview from one MSW
 handler

---
 frontend/src/__tests__/App.contract.test.tsx  |  91 +---------
 frontend/src/__tests__/ConfigStudio.test.tsx  |   2 +-
 frontend/src/__tests__/mocks/apiFixtures.ts   |   5 +-
 frontend/src/__tests__/mocks/server.ts        |   7 +
 .../useFeedCreation.contract.test.ts          |  57 +-----
 .../src/__tests__/useFeedCreation.test.ts     | 170 ++++++++----------
 6 files changed, 101 insertions(+), 231 deletions(-)

diff --git a/frontend/src/__tests__/App.contract.test.tsx b/frontend/src/__tests__/App.contract.test.tsx
index 214ec2e7..29e26262 100644
--- a/frontend/src/__tests__/App.contract.test.tsx
+++ b/frontend/src/__tests__/App.contract.test.tsx
@@ -1,15 +1,11 @@
-import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { describe, it, expect, beforeEach } from 'vitest';
 import { render, screen, fireEvent, waitFor } from '@testing-library/preact';
 import { http, HttpResponse } from 'msw';
-import { httpRequestUrl } from '../api/http/client';
 import { server, buildFeedResponse, buildStructuredErrorResponse } from './mocks/server';
+import { JSON_FEED_PREVIEW_PATH, jsonPreviewItems } from './mocks/apiFixtures';
 import { App } from '../components/App';
 import { COPY } from '../journey/copy';
 
-function isGeneratedPreview(input: RequestInfo | URL): boolean {
-  return httpRequestUrl(input).pathname.endsWith('/api/v1/feeds/generated-token.json');
-}
-
 describe('App contract', () => {
   const token = 'contract-token';
 
@@ -21,30 +17,6 @@ describe('App contract', () => {
   });
 
   it('shows feed result when the API returns structured create payload and preview feed', async () => {
-    const nativeFetch = fetch;
-    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockImplementation((input, init) => {
-      if (isGeneratedPreview(input)) {
-        expect((init?.headers as Record<string, string> | undefined)?.Accept).toBe('application/feed+json');
-        return Promise.resolve(
-          Response.json(
-            {
-              items: [
-                {
-                  title: 'Contract Item',
-                  content_text: 'Contract preview excerpt.',
-                  url: 'https://example.com/contract-item',
-                  date_published: '2024-01-01T00:00:00Z',
-                },
-              ],
-            },
-            { status: 200, headers: { 'Content-Type': 'application/feed+json' } }
-          )
-        );
-      }
-
-      return nativeFetch(input, init);
-    });
-
     server.use(
       http.post('/api/v1/feeds', async ({ request }) => {
         const body = (await request.json()) as { url: string };
@@ -62,37 +34,10 @@ describe('App contract', () => {
           { status: 201 }
         );
       }),
-      http.get('http://localhost:3000/api/v1/feeds/generated-token.json', ({ request }) => {
-        expect(request.headers.get('accept')).toBe('application/feed+json');
-
-        return HttpResponse.json(
-          {
-            items: [
-              {
-                title: 'Contract Item',
-                content_text: 'Contract preview excerpt.',
-                url: 'https://example.com/contract-item',
-                date_published: '2024-01-01T00:00:00Z',
-              },
-            ],
-          },
-          {
-            headers: { 'content-type': 'application/feed+json' },
-          }
-        );
-      }),
-      http.get('/api/v1/feeds/generated-token.json', ({ request }) => {
+      http.get(JSON_FEED_PREVIEW_PATH, ({ request }) => {
         expect(request.headers.get('accept')).toBe('application/feed+json');
-
-        return HttpResponse.json({
-          items: [
-            {
-              title: 'Contract Item',
-              content_text: 'Contract preview excerpt.',
-              url: 'https://example.com/contract-item',
-              date_published: '2024-01-01T00:00:00Z',
-            },
-          ],
+        return HttpResponse.json(jsonPreviewItems, {
+          headers: { 'content-type': 'application/feed+json' },
         });
       })
     );
@@ -116,8 +61,8 @@ describe('App contract', () => {
       expect(screen.getByRole('button', { name: COPY.copyFeedUrl })).toBeInTheDocument();
       expect(screen.getByRole('button', { name: COPY.createAnother })).toBeInTheDocument();
       expect(screen.getByText(COPY.previewItemCount(1))).toBeInTheDocument();
+      expect(screen.getByText('Sample preview item')).toBeInTheDocument();
     });
-    fetchSpy.mockRestore();
   });
 
   it('reopens the token gate when a saved token is rejected by structured auth metadata', async () => {
@@ -157,29 +102,6 @@ describe('App contract', () => {
   });
 
   it('posts refined selectors from the studio and returns to the result view', async () => {
-    const nativeFetch = fetch;
-    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockImplementation((input, init) => {
-      if (isGeneratedPreview(input)) {
-        return Promise.resolve(
-          Response.json(
-            {
-              items: [
-                {
-                  title: 'Contract Item',
-                  content_text: 'Contract preview excerpt.',
-                  url: 'https://example.com/contract-item',
-                  date_published: '2024-01-01T00:00:00Z',
-                },
-              ],
-            },
-            { status: 200, headers: { 'Content-Type': 'application/feed+json' } }
-          )
-        );
-      }
-
-      return nativeFetch(input, init);
-    });
-
     const bodies: unknown[] = [];
     server.use(
       http.post('/api/v1/feeds', async ({ request }) => {
@@ -251,7 +173,6 @@ describe('App contract', () => {
     });
     expect(postedSelectors(bodies[1])).toEqual({ items: { selector: 'a[href], article' } });
     await screen.findByText(COPY.feedReady);
-    fetchSpy.mockRestore();
   });
 });
 
diff --git a/frontend/src/__tests__/ConfigStudio.test.tsx b/frontend/src/__tests__/ConfigStudio.test.tsx
index e2c18a54..8ad55bb7 100644
--- a/frontend/src/__tests__/ConfigStudio.test.tsx
+++ b/frontend/src/__tests__/ConfigStudio.test.tsx
@@ -47,7 +47,7 @@ function previewEnvelope(items: Array<Record<string, unknown>>, quality?: Record
       item_count: items.length,
       sample_items: items,
       quality_report: quality ?? { warnings: [], metrics: { short_title_count: 0 } },
-      failure_kind: '',
+      failure_kind: null,
       validation_issues: [],
     },
   };
diff --git a/frontend/src/__tests__/mocks/apiFixtures.ts b/frontend/src/__tests__/mocks/apiFixtures.ts
index e98560c7..f592f738 100644
--- a/frontend/src/__tests__/mocks/apiFixtures.ts
+++ b/frontend/src/__tests__/mocks/apiFixtures.ts
@@ -211,7 +211,7 @@ export function studioPreviewSuccessBody(
       item_count: items.length,
       sample_items: items,
       quality_report: { warnings: [], metrics: { short_title_count: 0 } },
-      failure_kind: '',
+      failure_kind: null,
       validation_issues: [],
     },
   };
@@ -227,3 +227,6 @@ export const jsonPreviewItems = {
     },
   ],
 };
+
+/** Absolute and relative JSON Feed preview URLs from `resolveFetchUrl(json_public_url)`. */
+export const JSON_FEED_PREVIEW_PATH = /\/api\/v1\/feeds\/[^/?#]+\.json$/;
diff --git a/frontend/src/__tests__/mocks/server.ts b/frontend/src/__tests__/mocks/server.ts
index 4c5bc11d..686a6871 100644
--- a/frontend/src/__tests__/mocks/server.ts
+++ b/frontend/src/__tests__/mocks/server.ts
@@ -2,6 +2,8 @@ import { setupServer } from 'msw/node';
 import { http, HttpResponse } from 'msw';
 import {
   emptyCatalog,
+  JSON_FEED_PREVIEW_PATH,
+  jsonPreviewItems,
   metadataBody,
   pageUrlFrom,
   selectorsFromValidateRequest,
@@ -19,6 +21,11 @@ export const server = setupServer(
   http.get('/api/v1/configs', () => {
     return HttpResponse.json(emptyCatalog);
   }),
+  http.get(JSON_FEED_PREVIEW_PATH, () =>
+    HttpResponse.json(jsonPreviewItems, {
+      headers: { 'content-type': 'application/feed+json' },
+    })
+  ),
   http.post('/api/v1/feeds/validate', async ({ request }) => {
     const body = await request.json();
     const selectors = selectorsFromValidateRequest(body);
diff --git a/frontend/src/__tests__/useFeedCreation.contract.test.ts b/frontend/src/__tests__/useFeedCreation.contract.test.ts
index 070a10d6..50027773 100644
--- a/frontend/src/__tests__/useFeedCreation.contract.test.ts
+++ b/frontend/src/__tests__/useFeedCreation.contract.test.ts
@@ -1,33 +1,13 @@
-import { describe, it, expect, vi } from 'vitest';
+import { describe, it, expect } from 'vitest';
 import { renderHook, act, waitFor } from '@testing-library/preact';
 import { http, HttpResponse } from 'msw';
-import { httpRequestUrl } from '../api/http/client';
 import { server, buildFeedResponse, buildStructuredErrorResponse } from './mocks/server';
+import { JSON_FEED_PREVIEW_PATH } from './mocks/apiFixtures';
 import { useFeedCreation } from '../feed';
 
-function isGeneratedPreview(input: RequestInfo | URL): boolean {
-  return httpRequestUrl(input).pathname.endsWith('/api/v1/feeds/generated-token.json');
-}
-
 describe('useFeedCreation contract', () => {
   it('sends feed creation requests with bearer auth and hydrates preview from json_public_url', async () => {
     let receivedAuthorization: string | undefined;
-    const nativeFetch = fetch;
-    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockImplementation((input, init) => {
-      if (isGeneratedPreview(input)) {
-        return Promise.resolve(
-          Response.json(
-            { items: [{ title: 'Preview', content_text: 'Text' }] },
-            {
-              status: 200,
-              headers: { 'Content-Type': 'application/feed+json' },
-            }
-          )
-        );
-      }
-
-      return nativeFetch(input, init);
-    });
 
     server.use(
       http.post('/api/v1/feeds', async ({ request }) => {
@@ -45,16 +25,7 @@ describe('useFeedCreation contract', () => {
           }),
           { status: 201 }
         );
-      }),
-      http.get('http://localhost:3000/api/v1/feeds/generated-token.json', () =>
-        HttpResponse.json({ items: [{ title: 'Preview', content_text: 'Text' }] })
-      ),
-      http.get('http://localhost/api/v1/feeds/generated-token.json', () =>
-        HttpResponse.json({ items: [{ title: 'Preview', content_text: 'Text' }] })
-      ),
-      http.get('/api/v1/feeds/generated-token.json', () =>
-        HttpResponse.json({ items: [{ title: 'Preview', content_text: 'Text' }] })
-      )
+      })
     );
 
     const { result } = renderHook(() => useFeedCreation());
@@ -67,7 +38,7 @@ describe('useFeedCreation contract', () => {
     expect(result.current.error).toBeUndefined();
     expect(result.current.result?.feed.feed_token).toBe('generated-token');
     await waitFor(() => expect(result.current.result?.preview.status).toBe('preview_ready'));
-    fetchSpy.mockRestore();
+    expect(result.current.result?.preview.items[0]?.title).toBe('Sample preview item');
   });
 
   it('propagates structured auth failures without parsing the message text', async () => {
@@ -138,15 +109,6 @@ describe('useFeedCreation contract', () => {
   });
 
   it('marks preview failure from the feed json response without status polling', async () => {
-    const nativeFetch = fetch;
-    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockImplementation((input, init) => {
-      if (isGeneratedPreview(input)) {
-        return Promise.resolve(new Response('No feed items', { status: 422 }));
-      }
-
-      return nativeFetch(input, init);
-    });
-
     server.use(
       http.post('/api/v1/feeds', async ({ request }) => {
         const body = (await request.json()) as { url: string };
@@ -161,15 +123,7 @@ describe('useFeedCreation contract', () => {
           { status: 201 }
         );
       }),
-      http.get('http://localhost:3000/api/v1/feeds/generated-token.json', () =>
-        HttpResponse.text('No feed items', { status: 422 })
-      ),
-      http.get('http://localhost/api/v1/feeds/generated-token.json', () =>
-        HttpResponse.text('No feed items', { status: 422 })
-      ),
-      http.get('/api/v1/feeds/generated-token.json', () =>
-        HttpResponse.text('No feed items', { status: 422 })
-      )
+      http.get(JSON_FEED_PREVIEW_PATH, () => HttpResponse.text('No feed items', { status: 422 }))
     );
 
     const { result } = renderHook(() => useFeedCreation());
@@ -182,7 +136,6 @@ describe('useFeedCreation contract', () => {
       expect(result.current.result?.preview.status).toBe('preview_failed');
       expect(result.current.result?.warnings[0]?.code).toBe('PREVIEW_HTTP_422');
     });
-    fetchSpy.mockRestore();
   });
 
   it('rejects camelCase-only create payloads to enforce canonical snake_case contract', async () => {
diff --git a/frontend/src/__tests__/useFeedCreation.test.ts b/frontend/src/__tests__/useFeedCreation.test.ts
index 75e3ab33..99e07793 100644
--- a/frontend/src/__tests__/useFeedCreation.test.ts
+++ b/frontend/src/__tests__/useFeedCreation.test.ts
@@ -1,24 +1,10 @@
-import { describe, it, expect, beforeEach, afterEach, vi, type SpyInstance } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import { renderHook, act, waitFor } from '@testing-library/preact';
-import { httpRequestUrl } from '../api/http/client';
+import { http, HttpResponse } from 'msw';
+import { server, buildFeedResponse } from './mocks/server';
+import { JSON_FEED_PREVIEW_PATH, jsonPreviewItems } from './mocks/apiFixtures';
 import { useFeedCreation } from '../feed';
 
-function fetchInput(call: unknown[] | undefined): RequestInfo | URL | undefined {
-  const input = call?.[0];
-  if (typeof input === 'string' || input instanceof URL || input instanceof Request) return input;
-  return;
-}
-
-function isCreateFeedCall(call: unknown[] | undefined): boolean {
-  const input = fetchInput(call);
-  return input !== undefined && httpRequestUrl(input).pathname === '/api/v1/feeds';
-}
-
-function isJsonPreviewCall(call: unknown[] | undefined): boolean {
-  const input = fetchInput(call);
-  return input !== undefined && httpRequestUrl(input).pathname.endsWith('/api/v1/feeds/feed-token-1.json');
-}
-
 const mockFeed = {
   id: 'feed-1',
   name: 'Example Feed',
@@ -30,69 +16,56 @@ const mockFeed = {
   updated_at: '2024-01-01T00:00:00Z',
 };
 
-function createResponse(status = 201) {
-  return Response.json(
-    { success: true, data: { feed: mockFeed } },
-    {
-      status,
-      headers: { 'Content-Type': 'application/json' },
-    }
-  );
-}
-
-function previewResponse(status = 200) {
-  return Response.json(
-    {
-      items: [{ title: 'Preview item', content_text: 'Preview excerpt', date_published: '2024-01-02' }],
-    },
-    { status, headers: { 'Content-Type': 'application/feed+json' } }
+function useCreateFeedHandler() {
+  let createCount = 0;
+  server.use(
+    http.post('/api/v1/feeds', () => {
+      createCount += 1;
+      return HttpResponse.json(buildFeedResponse(mockFeed), { status: 201 });
+    })
   );
+  return () => createCount;
 }
 
 describe('useFeedCreation', () => {
-  let fetchMock: SpyInstance;
-
   beforeEach(() => {
-    vi.clearAllMocks();
     localStorage.clear();
     sessionStorage.clear();
-    fetchMock = vi.spyOn(globalThis, 'fetch');
   });
 
   afterEach(() => {
-    fetchMock.mockRestore();
+    vi.useRealTimers();
   });
 
   it('creates a feed from metadata and hydrates preview from json_public_url', async () => {
-    fetchMock.mockResolvedValueOnce(createResponse()).mockResolvedValueOnce(previewResponse());
+    useCreateFeedHandler();
 
     const { result } = renderHook(() => useFeedCreation());
     await act(async () => {
       await result.current.createFeed('https://example.com/articles', 'token-123');
     });
 
-    const createInput = fetchInput(fetchMock.mock.calls[0]);
-    expect(createInput).toBeDefined();
-    if (!createInput) return;
-    expect(httpRequestUrl(createInput).pathname).toBe('/api/v1/feeds');
-    const previewInput = fetchInput(fetchMock.mock.calls[1]);
-    expect(previewInput).toBeDefined();
-    if (!previewInput) return;
-    expect(httpRequestUrl(previewInput).pathname).toMatch(/\/api\/v1\/feeds\/feed-token-1\.json$/);
-    expect(fetchMock.mock.calls).toHaveLength(2);
-
     await waitFor(() => {
       expect(result.current.result?.preview.status).toBe('preview_ready');
-      expect(result.current.result?.preview.items[0]?.title).toBe('Preview item');
+      expect(result.current.result?.preview.items[0]?.title).toBe(jsonPreviewItems.items[0]?.title);
     });
   });
 
   it('retries only preview fetches on transient preview failure', async () => {
     vi.useFakeTimers();
-    fetchMock
-      .mockResolvedValueOnce(createResponse())
-      .mockResolvedValueOnce(new Response('', { status: 503 }))
-      .mockResolvedValueOnce(previewResponse());
+    const createCount = useCreateFeedHandler();
+    let previewAttempts = 0;
+    server.use(
+      http.get(JSON_FEED_PREVIEW_PATH, () => {
+        previewAttempts += 1;
+        if (previewAttempts === 1) {
+          return new HttpResponse('', { status: 503 });
+        }
+        return HttpResponse.json(jsonPreviewItems, {
+          headers: { 'content-type': 'application/feed+json' },
+        });
+      })
+    );
 
     const { result } = renderHook(() => useFeedCreation());
     await act(async () => {
@@ -106,16 +79,13 @@ describe('useFeedCreation', () => {
     await waitFor(() => {
       expect(result.current.result?.preview.status).toBe('preview_ready');
     });
-    expect(fetchMock.mock.calls.filter((call) => isCreateFeedCall(call)).length).toBe(1);
-    expect(fetchMock.mock.calls.filter((call) => isJsonPreviewCall(call)).length).toBe(2);
-
-    vi.useRealTimers();
+    expect(createCount()).toBe(1);
+    expect(previewAttempts).toBe(2);
   });
 
   it('marks preview failed for non-transient preview responses', async () => {
-    fetchMock
-      .mockResolvedValueOnce(createResponse())
-      .mockResolvedValueOnce(new Response('', { status: 422 }));
+    useCreateFeedHandler();
+    server.use(http.get(JSON_FEED_PREVIEW_PATH, () => new HttpResponse('', { status: 422 })));
 
     const { result } = renderHook(() => useFeedCreation());
     await act(async () => {
@@ -133,9 +103,19 @@ describe('useFeedCreation', () => {
   });
 
   it('retries preview without recreating the feed', async () => {
-    fetchMock
-      .mockResolvedValueOnce(createResponse())
-      .mockResolvedValueOnce(new Response('', { status: 422 }));
+    const createCount = useCreateFeedHandler();
+    let previewAttempts = 0;
+    server.use(
+      http.get(JSON_FEED_PREVIEW_PATH, () => {
+        previewAttempts += 1;
+        if (previewAttempts === 1) {
+          return new HttpResponse('', { status: 422 });
+        }
+        return HttpResponse.json(jsonPreviewItems, {
+          headers: { 'content-type': 'application/feed+json' },
+        });
+      })
+    );
 
     const { result } = renderHook(() => useFeedCreation());
     await act(async () => {
@@ -143,28 +123,32 @@ describe('useFeedCreation', () => {
     });
     await waitFor(() => expect(result.current.result?.preview.status).toBe('preview_failed'));
 
-    fetchMock.mockResolvedValueOnce(previewResponse());
     act(() => result.current.retryPreviewFetch());
 
     await waitFor(() => expect(result.current.result?.preview.status).toBe('preview_ready'));
-    expect(fetchMock.mock.calls.filter((call) => isCreateFeedCall(call)).length).toBe(1);
+    expect(createCount()).toBe(1);
   });
 
   it('keeps the creation audience when preview is retried', async () => {
-    const richPreview = () =>
-      Response.json(
-        {
-          items: [
-            { title: 'Shown', image: 'https://cdn.example/a.jpg' },
-            ...Array.from({ length: 9 }, (_, index) => ({ title: `Extra ${index}` })),
-          ],
-        },
-        { status: 200, headers: { 'Content-Type': 'application/feed+json' } }
-      );
-
-    fetchMock
-      .mockResolvedValueOnce(createResponse())
-      .mockResolvedValueOnce(new Response('', { status: 422 }));
+    useCreateFeedHandler();
+    let previewAttempts = 0;
+    const richPreview = {
+      items: [
+        { title: 'Shown', image: 'https://cdn.example/a.jpg' },
+        ...Array.from({ length: 9 }, (_, index) => ({ title: `Extra ${index}` })),
+      ],
+    };
+    server.use(
+      http.get(JSON_FEED_PREVIEW_PATH, () => {
+        previewAttempts += 1;
+        if (previewAttempts === 1) {
+          return new HttpResponse('', { status: 422 });
+        }
+        return HttpResponse.json(richPreview, {
+          headers: { 'content-type': 'application/feed+json' },
+        });
+      })
+    );
 
     const { result } = renderHook(() => useFeedCreation());
     await act(async () => {
@@ -172,7 +156,6 @@ describe('useFeedCreation', () => {
     });
     await waitFor(() => expect(result.current.result?.preview.status).toBe('preview_failed'));
 
-    fetchMock.mockResolvedValueOnce(richPreview());
     act(() => result.current.retryPreviewFetch());
 
     await waitFor(() => expect(result.current.result?.preview.status).toBe('preview_ready'));
@@ -181,16 +164,19 @@ describe('useFeedCreation', () => {
   });
 
   it('uses member richness when creation had an access token', async () => {
-    fetchMock.mockResolvedValueOnce(createResponse()).mockResolvedValueOnce(
-      Response.json(
-        {
-          items: [
-            { title: 'Shown', image: 'https://cdn.example/a.jpg' },
-            { title: 'Unsafe', image: 'javascript:alert(1)' },
-            ...Array.from({ length: 10 }, (_, index) => ({ title: `Extra ${index}` })),
-          ],
-        },
-        { status: 200, headers: { 'Content-Type': 'application/feed+json' } }
+    useCreateFeedHandler();
+    server.use(
+      http.get(JSON_FEED_PREVIEW_PATH, () =>
+        HttpResponse.json(
+          {
+            items: [
+              { title: 'Shown', image: 'https://cdn.example/a.jpg' },
+              { title: 'Unsafe', image: 'javascript:alert(1)' },
+              ...Array.from({ length: 10 }, (_, index) => ({ title: `Extra ${index}` })),
+            ],
+          },
+          { headers: { 'content-type': 'application/feed+json' } }
+        )
       )
     );
 

From 39db1173ecb1b2d40488e808bdfb7a579979691f Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Mon, 21 Sep 2026 23:59:58 +0200
Subject: [PATCH 100/108] test(frontend): render App against MSW instead of
 stubbed hooks

---
 frontend/package.json                        |   1 +
 frontend/pnpm-lock.yaml                      |  13 +
 frontend/src/__tests__/App.contract.test.tsx | 482 +++++++--
 frontend/src/__tests__/App.test.tsx          | 966 -------------------
 frontend/src/__tests__/mocks/apiFixtures.ts  |  37 +
 5 files changed, 428 insertions(+), 1071 deletions(-)
 delete mode 100644 frontend/src/__tests__/App.test.tsx

diff --git a/frontend/package.json b/frontend/package.json
index a0094175..4a34ac8e 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -34,6 +34,7 @@
     "@preact/preset-vite": "^2.10.6",
     "@testing-library/jest-dom": "^7.0.1",
     "@testing-library/preact": "^3.2.4",
+    "@testing-library/user-event": "14.6.7",
     "@typescript/native": "npm:typescript@^7.0.2",
     "baseline-browser-mapping": "^2.11.20",
     "eslint": "^10.9.1",
diff --git a/frontend/pnpm-lock.yaml b/frontend/pnpm-lock.yaml
index 1ad0f73f..d0b93c06 100644
--- a/frontend/pnpm-lock.yaml
+++ b/frontend/pnpm-lock.yaml
@@ -41,6 +41,9 @@ importers:
       '@testing-library/preact':
         specifier: ^3.2.4
         version: 3.2.4(preact@10.29.8)
+      '@testing-library/user-event':
+        specifier: 14.6.7
+        version: 14.6.7(@testing-library/dom@8.20.1)
       '@typescript/native':
         specifier: npm:typescript@^7.0.2
         version: typescript@7.0.2
@@ -622,6 +625,12 @@ packages:
     peerDependencies:
       preact: '>=10 || ^10.0.0-alpha.0 || ^10.0.0-beta.0'
 
+  '@testing-library/user-event@14.6.7':
+    resolution: {integrity: sha512-MPCpX8bxe8zS+JmmTwLp8jd0dy1rAm60Te/SL8JrQM3qvQJcBOs1d7IefJMyZzqM3EWBrDn/LWDt1BCGu4ASfg==}
+    engines: {node: '>=12', npm: '>=6'}
+    peerDependencies:
+      '@testing-library/dom': '>=7.21.4'
+
   '@types/aria-query@5.0.4':
     resolution: {integrity: sha512-rfT93uj5s0PRL7EzccGMs3brplhcrghnDoV26NqKhCAS1hVo+WdNsPvE/yb6ilfr5hi2MEk6d5EWJTKdxg8jVw==}
 
@@ -3077,6 +3086,10 @@ snapshots:
       '@testing-library/dom': 8.20.1
       preact: 10.29.8
 
+  '@testing-library/user-event@14.6.7(@testing-library/dom@8.20.1)':
+    dependencies:
+      '@testing-library/dom': 8.20.1
+
   '@types/aria-query@5.0.4': {}
 
   '@types/chai@5.2.3':
diff --git a/frontend/src/__tests__/App.contract.test.tsx b/frontend/src/__tests__/App.contract.test.tsx
index 29e26262..b3536e8f 100644
--- a/frontend/src/__tests__/App.contract.test.tsx
+++ b/frontend/src/__tests__/App.contract.test.tsx
@@ -1,39 +1,86 @@
-import { describe, it, expect, beforeEach } from 'vitest';
-import { render, screen, fireEvent, waitFor } from '@testing-library/preact';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { render, screen, waitFor, within, fireEvent } from '@testing-library/preact';
+import userEvent from '@testing-library/user-event';
 import { http, HttpResponse } from 'msw';
 import { server, buildFeedResponse, buildStructuredErrorResponse } from './mocks/server';
-import { JSON_FEED_PREVIEW_PATH, jsonPreviewItems } from './mocks/apiFixtures';
+import {
+  catalogBody,
+  catalogWireEntry,
+  JSON_FEED_PREVIEW_PATH,
+  jsonPreviewItems,
+  metadataBody,
+} from './mocks/apiFixtures';
 import { App } from '../components/App';
 import { COPY } from '../journey/copy';
+import { resetAccessTokenMemory } from '../session/accessToken';
 
-describe('App contract', () => {
-  const token = 'contract-token';
+const EXAMPLE_URL = 'https://example.com/articles';
+const DIRECTORY_HREF = 'https://html2rss.github.io/feed-directory/#!url=http%3A%2F%2Flocalhost%3A3000%2F';
+const ACCESS_TOKEN = 'member-token';
 
+const fao = catalogWireEntry({
+  id: 'fao.org/newsroom',
+  channelUrl: 'https://www.fao.org/newsroom',
+  title: 'FAO Newsroom',
+});
+const anthropic = catalogWireEntry({
+  id: 'anthropic.com/news',
+  channelUrl: 'https://www.anthropic.com/news',
+  title: 'Anthropic — News',
+});
+const bbcMundo = catalogWireEntry({
+  id: 'bbc.com/mundo',
+  channelUrl: 'https://www.bbc.com/mundo',
+  title: 'BBC — Mundo',
+});
+const bbcSounds = catalogWireEntry({
+  id: 'bbc.co.uk/available_episodes',
+  path: '/bbc.co.uk/available_episodes.rss',
+  channelUrl: 'https://www.bbc.co.uk/programmes/%<id>s/episodes/player',
+  title: 'BBC Sounds — Programme episodes',
+  parameterDefaults: { id: 'b006wkfp' },
+});
+
+function useSuccessfulCreate(createCount?: { value: number }) {
+  server.use(
+    http.post('/api/v1/feeds', async ({ request }) => {
+      if (createCount) createCount.value += 1;
+      const body = (await request.json()) as { url: string; selectors?: unknown };
+      return HttpResponse.json(
+        buildFeedResponse({
+          url: body.url,
+          feed_token: 'generated-token',
+          public_url: '/api/v1/feeds/generated-token',
+          json_public_url: '/api/v1/feeds/generated-token.json',
+        }),
+        { status: 201 }
+      );
+    })
+  );
+}
+
+async function renderApp(user = userEvent.setup()) {
+  render(<App />);
+  await screen.findByLabelText(COPY.urlLabel);
+  return user;
+}
+
+describe('App', () => {
   beforeEach(() => {
     history.replaceState({}, '', 'http://localhost:3000/#/create');
     localStorage.clear();
     sessionStorage.clear();
-    localStorage.setItem('html2rss_access_token', token);
+    resetAccessTokenMemory();
   });
 
-  it('shows feed result when the API returns structured create payload and preview feed', async () => {
-    server.use(
-      http.post('/api/v1/feeds', async ({ request }) => {
-        const body = (await request.json()) as { url: string };
-
-        expect(body).toEqual({ url: 'https://example.com/articles' });
-        expect(request.headers.get('authorization')).toBe(`Bearer ${token}`);
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
 
-        return HttpResponse.json(
-          buildFeedResponse({
-            url: body.url,
-            feed_token: 'generated-token',
-            public_url: '/api/v1/feeds/generated-token',
-            json_public_url: '/api/v1/feeds/generated-token.json',
-          }),
-          { status: 201 }
-        );
-      }),
+  it('shows feed result when create and JSON preview succeed', async () => {
+    localStorage.setItem('html2rss_access_token', ACCESS_TOKEN);
+    useSuccessfulCreate();
+    server.use(
       http.get(JSON_FEED_PREVIEW_PATH, ({ request }) => {
         expect(request.headers.get('accept')).toBe('application/feed+json');
         return HttpResponse.json(jsonPreviewItems, {
@@ -42,32 +89,194 @@ describe('App contract', () => {
       })
     );
 
+    const user = await renderApp();
+    expect(screen.queryByRole('combobox')).not.toBeInTheDocument();
+
+    await user.type(screen.getByLabelText(COPY.urlLabel), EXAMPLE_URL);
+    await user.click(screen.getByRole('button', { name: COPY.createFeed }));
+
+    await screen.findByText(COPY.feedReady);
+    expect(screen.getByText('Example Feed')).toBeInTheDocument();
+    expect(document.querySelector('.result-shell')).toHaveAttribute('data-state', 'result');
+    expect(screen.getByText(COPY.previewItemCount(1))).toBeInTheDocument();
+    expect(screen.getByText('Sample preview item')).toBeInTheDocument();
+  });
+
+  it('shows lean starters and hides them once the URL is non-empty', async () => {
+    localStorage.setItem('html2rss_access_token', ACCESS_TOKEN);
+    server.use(http.get('/api/v1/configs', () => HttpResponse.json(catalogBody([fao], [fao.id]))));
+
+    const user = await renderApp();
+
+    await screen.findByRole('link', { name: 'FAO Newsroom' });
+    expect(screen.getByRole('list', { name: COPY.feedDirectory })).toBeInTheDocument();
+    expect(screen.queryByText(COPY.feedDirectoryIntro)).not.toBeInTheDocument();
+
+    await user.type(screen.getByLabelText(COPY.urlLabel), 'example.com');
+    expect(screen.queryByRole('link', { name: 'FAO Newsroom' })).not.toBeInTheDocument();
+    expect(screen.queryByRole('list', { name: COPY.feedDirectory })).not.toBeInTheDocument();
+  });
+
+  it('opens the active catalog hit with ArrowDown then Enter without creating', async () => {
+    const assignSpy = vi.fn();
+    vi.stubGlobal('location', { ...location, assign: assignSpy });
+    localStorage.setItem('html2rss_access_token', ACCESS_TOKEN);
+    const createCount = { value: 0 };
+    useSuccessfulCreate(createCount);
+    server.use(
+      http.get('/api/v1/configs', () => HttpResponse.json(catalogBody([bbcMundo, bbcSounds])))
+    );
+
+    const user = await renderApp();
+    const urlField = screen.getByLabelText(COPY.urlLabel);
+    await user.type(urlField, 'bbc');
+    await screen.findByRole('listbox', { name: COPY.catalogFindHitsLabel });
+    await user.keyboard('{ArrowDown}{Enter}');
+
+    expect(assignSpy).toHaveBeenCalledWith('/bbc.co.uk/available_episodes.rss?id=b006wkfp');
+    expect(createCount.value).toBe(0);
+  });
+
+  it('does not double-create when Enter key-repeats', async () => {
+    localStorage.setItem('html2rss_access_token', ACCESS_TOKEN);
+    const createCount = { value: 0 };
+    useSuccessfulCreate(createCount);
+
+    const user = await renderApp();
+    const urlField = screen.getByLabelText(COPY.urlLabel);
+    await user.type(urlField, EXAMPLE_URL);
+    await user.keyboard('{Enter}');
+    urlField.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true, repeat: true }));
+    urlField.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true, repeat: true }));
+
+    await screen.findByText(COPY.feedReady);
+    expect(createCount.value).toBe(1);
+  });
+
+  it('surfaces retryable create errors with Decision copy', async () => {
+    localStorage.setItem('html2rss_access_token', ACCESS_TOKEN);
+    server.use(
+      http.post('/api/v1/feeds', () =>
+        HttpResponse.json(
+          buildStructuredErrorResponse({
+            message: 'Access denied',
+            kind: 'server',
+            retryable: true,
+            next_action: 'retry',
+            retry_action: 'primary',
+          }),
+          { status: 500 }
+        )
+      )
+    );
+
+    const user = await renderApp();
+    await user.type(screen.getByLabelText(COPY.urlLabel), EXAMPLE_URL);
+    await user.click(screen.getByRole('button', { name: COPY.createFeed }));
+
+    await screen.findByText(COPY.createFailedRetryTitle);
+    expect(screen.getByText('Access denied')).toBeInTheDocument();
+  });
+
+  it('shows instance metadata failure as a banner without create-error chrome', async () => {
+    server.use(http.get(/\/api\/v1\/?$/, () => HttpResponse.json({ success: false }, { status: 503 })));
+
     render(<App />);
+    await screen.findByText(COPY.instanceMetadataUnavailable);
+    expect(screen.getByText(COPY.instanceUnavailable)).toBeInTheDocument();
+    expect(screen.queryByText(COPY.createFailedTitle)).not.toBeInTheDocument();
+  });
 
-    await waitFor(() => {
-      expect(screen.getByLabelText(COPY.urlLabel)).toBeInTheDocument();
-    });
-    expect(screen.queryByRole('combobox')).not.toBeInTheDocument();
+  it('keeps utility order guest then member, and remaps local OpenAPI to the frontend origin', async () => {
+    server.use(
+      http.get(/\/api\/v1\/?$/, () =>
+        HttpResponse.json(metadataBody({ openapiUrl: 'http://127.0.0.1:4000/openapi.yaml' }))
+      )
+    );
 
-    const urlInput = screen.getByLabelText(COPY.urlLabel) as HTMLInputElement;
-    fireEvent.input(urlInput, { target: { value: 'https://example.com/articles' } });
-    fireEvent.click(screen.getByRole('button', { name: COPY.createFeed }));
+    await renderApp();
 
+    const utilities = screen.getByLabelText(COPY.utilities);
+    expect(
+      [...utilities.querySelectorAll(':scope .utility-strip__items > a')].map((link) => link.textContent)
+    ).toEqual([
+      COPY.browseFeedDirectory(),
+      COPY.bookmarkletTitle,
+      COPY.dockerInstall,
+      COPY.openapiSpec,
+      COPY.sourceCode,
+    ]);
+    expect(screen.getByRole('link', { name: COPY.openapiSpec })).toHaveAttribute(
+      'href',
+      'http://localhost:3000/openapi.yaml'
+    );
+    expect(screen.getByRole('link', { name: COPY.browseFeedDirectory() })).toHaveAttribute(
+      'href',
+      DIRECTORY_HREF
+    );
+  });
+
+  it('places logout before Docker install when a token is saved', async () => {
+    localStorage.setItem('html2rss_access_token', ACCESS_TOKEN);
+
+    await renderApp();
+    await screen.findByRole('button', { name: COPY.logout });
+
+    expect(
+      [
+        ...screen
+          .getByLabelText(COPY.utilities)
+          .querySelectorAll(':scope .utility-strip__items > a, :scope .utility-strip__items > button'),
+      ].map((element) => element.textContent)
+    ).toEqual([
+      COPY.browseFeedDirectory(),
+      COPY.bookmarkletTitle,
+      COPY.logout,
+      COPY.dockerInstall,
+      COPY.openapiSpec,
+      COPY.sourceCode,
+    ]);
+  });
+
+  it('prefills bookmarklet hash URLs over a saved draft', async () => {
+    localStorage.setItem(
+      'html2rss_feed_draft_state',
+      JSON.stringify({ url: 'https://old.example.com/page' })
+    );
+    history.replaceState({}, '', 'http://localhost:3000/#/create?url=https%3A%2F%2Fexample.com%2Farticles');
+
+    await renderApp();
     await waitFor(() => {
-      expect(screen.getByText(COPY.feedReady)).toBeInTheDocument();
-      expect(screen.getByText('Example Feed')).toBeInTheDocument();
-      expect(document.querySelector('.result-shell')).toHaveAttribute('data-state', 'result');
-      expect(screen.getByLabelText(COPY.feedUrl)).toBeInTheDocument();
-      expect(screen.getByRole('button', { name: COPY.copyFeedUrl })).toBeInTheDocument();
-      expect(screen.getByRole('button', { name: COPY.createAnother })).toBeInTheDocument();
-      expect(screen.getByText(COPY.previewItemCount(1))).toBeInTheDocument();
-      expect(screen.getByText('Sample preview item')).toBeInTheDocument();
+      expect(screen.getByLabelText(COPY.urlLabel)).toHaveValue(EXAMPLE_URL);
     });
+    expect(screen.getByRole('link', { name: COPY.bookmarkletTitle }).getAttribute('href')).toContain(
+      '/#/create?url='
+    );
   });
 
-  it('reopens the token gate when a saved token is rejected by structured auth metadata', async () => {
+  it('saves a token from the prompt and resumes create', async () => {
+    useSuccessfulCreate();
+    const user = await renderApp();
+
+    await user.type(screen.getByLabelText(COPY.urlLabel), EXAMPLE_URL);
+    await user.click(screen.getByRole('button', { name: COPY.createFeed }));
+
+    await screen.findByRole('heading', { name: COPY.tokenTitle });
+    expect(location.hash).toMatch(/^#\/token/);
+    expect(screen.getByLabelText(COPY.urlLabel)).toBeInTheDocument();
+
+    await user.type(document.querySelector('#access-token') as HTMLInputElement, 'token-123');
+    await user.click(screen.getByRole('button', { name: COPY.saveAndContinue }));
+
+    await screen.findByText(COPY.feedReady);
+    expect(localStorage.getItem('html2rss_access_token')).toBe('token-123');
+    expect(sessionStorage.getItem('html2rss_access_token')).toBeNull();
+  });
+
+  it('reopens the token gate on auth rejection and ignores non-token forbidden', async () => {
+    localStorage.setItem('html2rss_access_token', ACCESS_TOKEN);
     server.use(
-      http.post('/api/v1/feeds', async () =>
+      http.post('/api/v1/feeds', () =>
         HttpResponse.json(
           buildStructuredErrorResponse({
             code: 'UNAUTHORIZED',
@@ -82,32 +291,85 @@ describe('App contract', () => {
       )
     );
 
-    render(<App />);
-
-    await waitFor(() => {
-      expect(screen.getByLabelText(COPY.urlLabel)).toBeInTheDocument();
-    });
-
-    fireEvent.input(screen.getByLabelText(COPY.urlLabel), {
-      target: { value: 'https://example.com/articles' },
-    });
-    fireEvent.click(screen.getByRole('button', { name: COPY.createFeed }));
+    const user = await renderApp();
+    await user.type(screen.getByLabelText(COPY.urlLabel), EXAMPLE_URL);
+    await user.click(screen.getByRole('button', { name: COPY.createFeed }));
 
     await screen.findByText(COPY.tokenRejected);
-
     expect(screen.getByRole('heading', { name: COPY.tokenTitle })).toBeInTheDocument();
-    expect(screen.queryByText(COPY.createFailedTitle)).not.toBeInTheDocument();
     expect(localStorage.getItem('html2rss_access_token')).toBeNull();
-    expect(sessionStorage.getItem('html2rss_access_token')).toBeNull();
+  });
+
+  it('does not treat non-token forbidden failures as token rejection', async () => {
+    localStorage.setItem('html2rss_access_token', ACCESS_TOKEN);
+    server.use(
+      http.post('/api/v1/feeds', () =>
+        HttpResponse.json(
+          buildStructuredErrorResponse({
+            code: 'FORBIDDEN',
+            message: 'URL not allowed for this account',
+            kind: 'server',
+            retryable: false,
+            next_action: 'none',
+            retry_action: 'none',
+          }),
+          { status: 403 }
+        )
+      )
+    );
+
+    const user = await renderApp();
+    await user.type(screen.getByLabelText(COPY.urlLabel), EXAMPLE_URL);
+    await user.click(screen.getByRole('button', { name: COPY.createFeed }));
+
+    await screen.findByText('URL not allowed for this account');
+    expect(screen.queryByRole('heading', { name: COPY.tokenTitle })).not.toBeInTheDocument();
+    expect(screen.queryByText(COPY.tokenRejected)).not.toBeInTheDocument();
+    expect(localStorage.getItem('html2rss_access_token')).toBe(ACCESS_TOKEN);
+  });
+
+  it('clears creation chrome when remounting create via BrandLockup', async () => {
+    localStorage.setItem('html2rss_access_token', ACCESS_TOKEN);
+    server.use(
+      http.post('/api/v1/feeds', () =>
+        HttpResponse.json(
+          buildStructuredErrorResponse({
+            message: 'Upstream failed',
+            kind: 'server',
+            retryable: true,
+            next_action: 'retry',
+            retry_action: 'primary',
+          }),
+          { status: 500 }
+        )
+      )
+    );
+
+    const user = await renderApp();
+    await user.type(screen.getByLabelText(COPY.urlLabel), EXAMPLE_URL);
+    await user.click(screen.getByRole('button', { name: COPY.createFeed }));
+    await screen.findByText(COPY.createFailedRetryTitle);
+
+    await user.click(screen.getByRole('link', { name: 'html2rss' }));
+
+    await waitFor(() => {
+      expect(screen.queryByText(COPY.createFailedRetryTitle)).not.toBeInTheDocument();
+      expect(screen.queryByText(COPY.createFailedTitle)).not.toBeInTheDocument();
+    });
+    expect(document.querySelector('.form-shell')).toHaveAttribute('data-state', 'create');
   });
 
   it('posts refined selectors from the studio and returns to the result view', async () => {
+    localStorage.setItem('html2rss_access_token', ACCESS_TOKEN);
     const bodies: unknown[] = [];
     server.use(
       http.post('/api/v1/feeds', async ({ request }) => {
         const body: unknown = await request.json();
         bodies.push(body);
-        const url = readUrl(body) ?? 'https://example.com/articles';
+        const url =
+          body && typeof body === 'object' && 'url' in body && typeof body.url === 'string'
+            ? body.url
+            : EXAMPLE_URL;
 
         return HttpResponse.json(
           buildFeedResponse({
@@ -121,67 +383,77 @@ describe('App contract', () => {
       })
     );
 
+    const user = userEvent.setup();
     render(<App />);
+    const urlField = await screen.findByLabelText(COPY.urlLabel);
+    fireEvent.input(urlField, { target: { value: EXAMPLE_URL } });
+    await user.click(screen.getByRole('button', { name: COPY.createFeed }));
+    await screen.findByText(COPY.feedReady);
 
-    await waitFor(() => {
-      expect(screen.getByLabelText(COPY.urlLabel)).toBeInTheDocument();
-    });
+    await user.click(screen.getByRole('button', { name: COPY.refineSelectors }));
+    const itemsSelector = await screen.findByLabelText(COPY.itemsSelector);
+    await waitFor(() => expect(itemsSelector).toHaveValue('a[href]'));
+    await user.click(await screen.findByRole('button', { name: COPY.addSelector('article') }));
+    await waitFor(() => expect(itemsSelector).toHaveValue('a[href], article'));
 
-    fireEvent.input(screen.getByLabelText(COPY.urlLabel), {
-      target: { value: 'https://example.com/articles' },
-    });
-    fireEvent.click(screen.getByRole('button', { name: COPY.createFeed }));
+    const save = screen.getByRole('button', { name: COPY.saveAndGenerate });
+    await waitFor(() => expect(save).toBeEnabled());
+    await user.click(save);
 
+    await waitFor(() => expect(bodies).toHaveLength(2));
+    expect(bodies[1]).toMatchObject({ url: EXAMPLE_URL });
+    expect(
+      bodies[1] && typeof bodies[1] === 'object' && 'selectors' in bodies[1]
+        ? bodies[1].selectors
+        : undefined
+    ).toEqual({ items: { selector: 'a[href], article' } });
     await screen.findByText(COPY.feedReady);
-    expect(document.querySelector('.result-shell')).toHaveAttribute('data-state', 'result');
-    await waitFor(() => {
-      expect(document.querySelectorAll('.ui-item-list')).toHaveLength(1);
-    });
-    expect(screen.queryByLabelText(COPY.itemsSelector)).not.toBeInTheDocument();
-    expect(screen.getByRole('button', { name: COPY.refineSelectors })).toHaveAttribute(
-      'aria-expanded',
-      'false'
-    );
+  });
 
-    fireEvent.click(screen.getByRole('button', { name: COPY.refineSelectors }));
-    expect(screen.queryByLabelText(COPY.urlLabel)).not.toBeInTheDocument();
-    const itemsSelector = await screen.findByLabelText(COPY.itemsSelector);
-    await waitFor(() => {
-      expect(itemsSelector).toHaveValue('a[href]');
-    });
-    const addArticle = await screen.findByRole('button', { name: COPY.addSelector('article') });
-    fireEvent.click(addArticle);
-    await waitFor(() => {
-      expect(itemsSelector).toHaveValue('a[href], article');
-    });
-    expect(screen.getByRole('button', { name: COPY.removeSelector('article') })).toHaveAttribute(
-      'aria-pressed',
-      'true'
+  it('promotes starters when feed creation is disabled', async () => {
+    server.use(
+      http.get(/\/api\/v1\/?$/, () =>
+        HttpResponse.json({
+          success: true,
+          data: {
+            api: {
+              name: 'html2rss-web API',
+              description: 'd',
+              openapi_url: 'https://example.test/openapi.yaml',
+            },
+            instance: {
+              feed_creation: { enabled: false, access_token_required: false },
+              studio: { enabled: true },
+              catalog: { enabled: true, url: 'https://api.html2rss.dev/api/v1/configs' },
+            },
+          },
+        })
+      ),
+      http.get('/api/v1/configs', () => HttpResponse.json(catalogBody([fao], [fao.id])))
     );
-    expect(screen.getByLabelText(COPY.enhanceItems)).not.toBeChecked();
-    const save = screen.getByRole('button', { name: COPY.saveAndGenerate });
-    await waitFor(() => expect(save).toBeEnabled());
-    expect(document.querySelectorAll('.ui-item-list')).toHaveLength(1);
-    expect(document.querySelector('.ui-card')).toBeNull();
-    fireEvent.click(save);
 
+    await renderApp();
     await waitFor(() => {
-      expect(bodies).toHaveLength(2);
+      expect(document.querySelector('.notice__title')?.textContent).toBe(COPY.feedDirectory);
     });
-    expect(bodies[1]).toMatchObject({
-      url: 'https://example.com/articles',
-    });
-    expect(postedSelectors(bodies[1])).toEqual({ items: { selector: 'a[href], article' } });
-    await screen.findByText(COPY.feedReady);
+    expect(screen.getByRole('link', { name: 'FAO Newsroom' })).toBeInTheDocument();
+    expect(screen.getByText(COPY.creationDisabled)).toBeInTheDocument();
   });
-});
 
-function readUrl(body: unknown): string | undefined {
-  if (!body || typeof body !== 'object' || !('url' in body)) return undefined;
-  return typeof body.url === 'string' ? body.url : undefined;
-}
+  it('lists catalog find hits for a text query', async () => {
+    server.use(
+      http.get('/api/v1/configs', () => HttpResponse.json(catalogBody([bbcMundo, bbcSounds, anthropic])))
+    );
 
-function postedSelectors(body: unknown): unknown {
-  if (!body || typeof body !== 'object' || !('selectors' in body)) return undefined;
-  return body.selectors;
-}
+    const user = await renderApp();
+    await user.type(screen.getByLabelText(COPY.urlLabel), 'bbc');
+
+    await screen.findByRole('option', { name: 'BBC — Mundo' });
+    expect(screen.getByRole('option', { name: 'BBC Sounds — Programme episodes' })).toHaveAttribute(
+      'href',
+      '/bbc.co.uk/available_episodes.rss?id=b006wkfp'
+    );
+    expect(screen.getByRole('listbox', { name: COPY.catalogFindHitsLabel })).toBeInTheDocument();
+    expect(within(screen.getByRole('status')).getByText(COPY.catalogFindHint)).toBeInTheDocument();
+  });
+});
diff --git a/frontend/src/__tests__/App.test.tsx b/frontend/src/__tests__/App.test.tsx
deleted file mode 100644
index 4d87f4d5..00000000
--- a/frontend/src/__tests__/App.test.tsx
+++ /dev/null
@@ -1,966 +0,0 @@
-import { describe, it, expect, beforeEach, vi } from 'vitest';
-import { render, screen, fireEvent, waitFor } from '@testing-library/preact';
-import type { FeedCreationError } from '../api/contracts';
-import { App } from '../components/App';
-import { COPY } from '../journey/copy';
-
-vi.mock('../session/accessToken', () => ({
-  useAccessToken: vi.fn(),
-  resetAccessTokenMemory: vi.fn(),
-}));
-
-vi.mock('../feed/useFeedCreation', () => ({
-  useFeedCreation: vi.fn(),
-}));
-
-vi.mock('../hooks/useApiMetadata', () => ({
-  useApiMetadata: vi.fn(),
-}));
-
-vi.mock('../catalog/useCatalogEntries', () => ({
-  useCatalogEntries: vi.fn(() => ({ entries: [], starters: [] })),
-}));
-
-import { useAccessToken } from '../session/accessToken';
-import { useApiMetadata } from '../hooks/useApiMetadata';
-import { useFeedCreation } from '../feed/useFeedCreation';
-import { useCatalogEntries } from '../catalog/useCatalogEntries';
-
-const mockUseAccessToken = useAccessToken as any;
-const mockUseApiMetadata = useApiMetadata as any;
-const mockUseFeedCreation = useFeedCreation as any;
-const mockUseCatalogEntries = useCatalogEntries as any;
-
-const EXAMPLE_URL = 'https://example.com/articles';
-const DIRECTORY_HREF = 'https://html2rss.github.io/feed-directory/#!url=http%3A%2F%2Flocalhost%3A3000%2F';
-
-const catalogHook = (entries: unknown[] = [], starters?: string[]) => ({
-  entries,
-  starters: starters ?? entries.map((entry: any) => entry.id).slice(0, 3),
-});
-
-const mockCreatedFeedResult = {
-  feed: {
-    id: 'feed-123',
-    name: 'Example Feed',
-    url: EXAMPLE_URL,
-    feed_token: 'generated-token',
-    public_url: '/api/v1/feeds/generated-token',
-    json_public_url: '/api/v1/feeds/generated-token.json',
-  },
-  preview: {
-    status: 'created' as const,
-    items: [],
-    isLoading: true,
-  },
-  warnings: [],
-};
-
-type CatalogEntry = {
-  id: string;
-  path: string;
-  title: string;
-  description: string;
-  channelUrl: string;
-  parameterDefaults: Record<string, string>;
-  lastResult: { state: string };
-};
-
-function catalogEntry(
-  id: string,
-  title: string,
-  channelUrl: string,
-  path = `/${id}.rss`,
-  parameterDefaults: Record<string, string> = {}
-): CatalogEntry {
-  return {
-    id,
-    path,
-    title,
-    description: `${title} description.`,
-    channelUrl,
-    parameterDefaults,
-    lastResult: { state: 'unknown' },
-  };
-}
-
-const faoStarter = catalogEntry('fao.org/newsroom', 'FAO Newsroom', 'https://www.fao.org/newsroom');
-const anthropicNews = catalogEntry(
-  'anthropic.com/news',
-  'Anthropic — News',
-  'https://www.anthropic.com/news'
-);
-const bbcMundo = catalogEntry('bbc.com/mundo', 'BBC — Mundo', 'https://www.bbc.com/mundo');
-const bbcSounds = catalogEntry(
-  'bbc.co.uk/available_episodes',
-  'BBC Sounds — Programme episodes',
-  'https://www.bbc.co.uk/programmes/%<id>s/episodes/player',
-  '/bbc.co.uk/available_episodes.rss',
-  { id: 'b006wkfp' }
-);
-
-async function expectCreateRemountedWithoutErrorChrome() {
-  await waitFor(() => {
-    expect(screen.queryByText(COPY.createFailedTitle)).not.toBeInTheDocument();
-    expect(screen.queryByText(COPY.createFailedRetryTitle)).not.toBeInTheDocument();
-  });
-  expect(document.querySelector('.form-shell')).toHaveAttribute('data-state', 'create');
-  await waitFor(() => {
-    expect(document.activeElement).toBe(screen.getByLabelText(COPY.urlLabel));
-  });
-}
-
-const mockSaveToken = vi.fn();
-const mockClearToken = vi.fn();
-const mockCreateFeed = vi.fn();
-const mockClearCreationError = vi.fn();
-const mockClearResult = vi.fn();
-const mockRetryPreviewFetch = vi.fn();
-
-function stubAccessToken(options: { token?: string; hasToken?: boolean; error?: string } = {}) {
-  mockUseAccessToken.mockReturnValue({
-    token: options.token,
-    hasToken: options.hasToken ?? Boolean(options.token),
-    saveToken: mockSaveToken,
-    clearToken: mockClearToken,
-    isLoading: false,
-    error: options.error,
-  });
-}
-
-function stubMetadata(
-  options: {
-    creationEnabled?: boolean;
-    tokenRequired?: boolean;
-    studioEnabled?: boolean;
-    openapiUrl?: string;
-    error?: string;
-  } = {}
-) {
-  if (options.error !== undefined) {
-    mockUseApiMetadata.mockReturnValue({
-      metadata: undefined,
-      isLoading: false,
-      error: options.error,
-    });
-    return;
-  }
-  mockUseApiMetadata.mockReturnValue({
-    metadata: {
-      api: {
-        name: 'html2rss-web API',
-        description: 'RESTful API for converting websites to RSS feeds',
-        openapi_url: options.openapiUrl ?? 'https://example.test/openapi.yaml',
-      },
-      instance: {
-        feed_creation: {
-          enabled: options.creationEnabled ?? true,
-          access_token_required: options.tokenRequired ?? true,
-        },
-        studio: { enabled: options.studioEnabled ?? true },
-        catalog: { enabled: true, url: '/api/v1/configs' },
-      },
-    },
-    isLoading: false,
-    error: undefined,
-  });
-}
-
-function stubCreation(
-  options: {
-    isCreating?: boolean;
-    result?: unknown;
-    error?: FeedCreationError;
-  } = {}
-) {
-  mockUseFeedCreation.mockReturnValue({
-    isCreating: options.isCreating ?? false,
-    result: options.result,
-    error: options.error,
-    createFeed: mockCreateFeed,
-    clearError: mockClearCreationError,
-    clearResult: mockClearResult,
-    retryPreviewFetch: mockRetryPreviewFetch,
-  });
-}
-
-function fillUrl(url = EXAMPLE_URL) {
-  fireEvent.input(screen.getByLabelText(COPY.urlLabel), { target: { value: url } });
-}
-
-function clickCreate() {
-  fireEvent.click(screen.getByRole('button', { name: COPY.createFeed }));
-}
-
-function withMemberSession(token = 'saved-token') {
-  stubAccessToken({ token });
-}
-
-describe('App', () => {
-  /** Mirrors useFeedCreation: reject sets error; clearError clears it (App mock was static). */
-  let creationHookError: FeedCreationError | undefined;
-
-  beforeEach(() => {
-    vi.clearAllMocks();
-    creationHookError = undefined;
-    history.replaceState({}, '', 'http://localhost:3000/#/create');
-    localStorage.clear();
-    mockCreateFeed.mockResolvedValue(mockCreatedFeedResult);
-    mockClearCreationError.mockImplementation(() => {
-      creationHookError = undefined;
-    });
-    mockUseCatalogEntries.mockReturnValue(catalogHook());
-    stubAccessToken();
-    stubMetadata();
-
-    mockUseFeedCreation.mockImplementation(() => ({
-      isCreating: false,
-      result: undefined,
-      error: creationHookError,
-      createFeed: async (url: string, token: string) => {
-        try {
-          return await mockCreateFeed(url, token);
-        } catch (error) {
-          creationHookError = error as FeedCreationError;
-          throw error;
-        }
-      },
-      clearError: mockClearCreationError,
-      clearResult: mockClearResult,
-      retryPreviewFetch: mockRetryPreviewFetch,
-    }));
-  });
-
-  const creationFailure = {
-    kind: 'server' as const,
-    code: 'INTERNAL_SERVER_ERROR' as const,
-    retryable: true,
-    nextAction: 'retry' as const,
-    retryAction: 'primary' as const,
-    message: 'Access denied',
-  };
-
-  async function renderCreateWithCreationError() {
-    stubMetadata({ tokenRequired: false });
-    mockCreateFeed.mockRejectedValue(creationFailure);
-    render(<App />);
-    fillUrl();
-    clickCreate();
-    await waitFor(() => {
-      expect(screen.getByText(COPY.createFailedRetryTitle)).toBeInTheDocument();
-    });
-  }
-
-  function serverError(
-    message: string,
-    retryAction: 'primary' | 'alternate' | 'none' = 'primary'
-  ): FeedCreationError {
-    return {
-      kind: 'server',
-      code: 'INTERNAL_SERVER_ERROR',
-      retryable: retryAction !== 'none',
-      nextAction: retryAction === 'none' ? 'none' : 'retry',
-      retryAction,
-      message,
-    };
-  }
-
-  it('renders create shell with permissive URL field and autofocus', async () => {
-    render(<App />);
-
-    expect(screen.getByLabelText('html2rss')).toBeInTheDocument();
-    expect(screen.getByRole('link', { name: 'html2rss' }).getAttribute('href')).toMatch(/#\/create$/);
-    expect(screen.queryByRole('combobox')).not.toBeInTheDocument();
-    expect(screen.getByLabelText(COPY.utilities)).toBeInTheDocument();
-    expect(screen.getByRole('link', { name: COPY.bookmarkletTitle })).toBeInTheDocument();
-    expect(document.querySelector('.form-shell')).toHaveAttribute('data-state', 'create');
-
-    const urlInput = screen.getByLabelText(COPY.urlLabel);
-    expect(urlInput).toHaveAttribute('type', 'text');
-    expect(urlInput).toHaveAttribute('inputmode', 'url');
-    expect(urlInput).toHaveAttribute('autocapitalize', 'off');
-    await waitFor(() => {
-      expect(document.activeElement).toBe(urlInput);
-    });
-  });
-
-  it('submits create requests without exposing strategy selection', async () => {
-    withMemberSession();
-    render(<App />);
-    fillUrl();
-    clickCreate();
-
-    await waitFor(() => {
-      expect(mockCreateFeed).toHaveBeenCalledWith(EXAMPLE_URL, 'saved-token');
-    });
-  });
-
-  it('submits create requests when Enter is pressed on the URL field', async () => {
-    withMemberSession();
-    render(<App />);
-    fillUrl();
-    fireEvent.keyDown(screen.getByLabelText(COPY.urlLabel), { key: 'Enter' });
-
-    await waitFor(() => {
-      expect(mockCreateFeed).toHaveBeenCalledWith(EXAMPLE_URL, 'saved-token');
-    });
-  });
-
-  it('does not submit extra create requests when Enter key-repeats', async () => {
-    withMemberSession();
-    render(<App />);
-    fillUrl();
-    const urlField = screen.getByLabelText(COPY.urlLabel);
-    fireEvent.keyDown(urlField, { key: 'Enter' });
-    fireEvent.keyDown(urlField, { key: 'Enter', repeat: true });
-    fireEvent.keyDown(urlField, { key: 'Enter', repeat: true });
-
-    await waitFor(() => {
-      expect(mockCreateFeed).toHaveBeenCalledTimes(1);
-    });
-    expect(mockCreateFeed).toHaveBeenCalledWith(EXAMPLE_URL, 'saved-token');
-  });
-
-  it('auto-submits a prefilled url without persisting strategy state', async () => {
-    withMemberSession();
-    history.replaceState({}, '', 'http://localhost:3000/?url=https%3A%2F%2Fexample.com%2Farticles');
-    render(<App />);
-
-    await waitFor(() => {
-      expect(mockCreateFeed).toHaveBeenCalledWith(EXAMPLE_URL, 'saved-token');
-      expect(location.hash).toBe('#/result/generated-token');
-    });
-  });
-
-  it('recovers unmatched result deep links onto remounted create without url prefill', async () => {
-    history.replaceState({}, '', 'http://localhost:3000/#/result/generated-token');
-    render(<App />);
-
-    await waitFor(() => {
-      expect(location.hash).toBe('#/create');
-    });
-    expect(location.hash).not.toContain('url=');
-    expect(screen.getByLabelText(COPY.urlLabel)).toBeInTheDocument();
-    expect(document.querySelector('.form-shell')).toHaveAttribute('data-state', 'create');
-    expect(screen.queryByRole('heading', { name: 'Saved result unavailable' })).not.toBeInTheDocument();
-    expect(screen.queryByText(COPY.createFailedTitle)).not.toBeInTheDocument();
-  });
-
-  it('remounts create from BrandLockup and clears creation chrome', async () => {
-    await renderCreateWithCreationError();
-    const createCalls = mockCreateFeed.mock.calls.length;
-    fireEvent.click(screen.getByRole('link', { name: 'html2rss' }));
-    await expectCreateRemountedWithoutErrorChrome();
-    expect(mockCreateFeed).toHaveBeenCalledTimes(createCalls);
-  });
-
-  it('remounts create from a #/create visit and clears creation chrome', async () => {
-    await renderCreateWithCreationError();
-    const createCalls = mockCreateFeed.mock.calls.length;
-    dispatchEvent(new HashChangeEvent('hashchange'));
-    await expectCreateRemountedWithoutErrorChrome();
-    expect(location.hash).toBe('#/create');
-    expect(mockCreateFeed).toHaveBeenCalledTimes(createCalls);
-  });
-
-  it('remounts create from a hashbang entry and clears creation chrome', async () => {
-    await renderCreateWithCreationError();
-    const createCalls = mockCreateFeed.mock.calls.length;
-    location.hash = '#!/create';
-    await waitFor(() => {
-      expect(location.hash).toBe('#/create');
-    });
-    await expectCreateRemountedWithoutErrorChrome();
-    expect(mockCreateFeed).toHaveBeenCalledTimes(createCalls);
-  });
-
-  it('shows inline token prompt when submitting without a token', async () => {
-    render(<App />);
-    fillUrl();
-    clickCreate();
-
-    expect(screen.getByRole('heading', { name: COPY.tokenTitle })).toBeInTheDocument();
-    expect(location.hash).toMatch(/^#\/token/);
-    expect(document.querySelector('.form-shell')).toHaveAttribute('data-state', 'token_prompt');
-    expect(document.querySelector('dialog')).toHaveAttribute('open');
-    expect(screen.getByLabelText(COPY.urlLabel)).toBeInTheDocument();
-    expect(screen.getByLabelText(COPY.urlLabel).closest('[inert]')).not.toBeNull();
-    expect(screen.queryByText(COPY.createFailedTitle)).not.toBeInTheDocument();
-    expect(screen.queryByRole('combobox')).not.toBeInTheDocument();
-    expect(screen.getByLabelText(COPY.utilities)).toBeInTheDocument();
-    expect(screen.getByRole('link', { name: COPY.dockerSetup })).toBeInTheDocument();
-    expect(screen.getByText(COPY.tokenHint)).toBeInTheDocument();
-    expect(screen.queryByText('Paste an access token to keep going.')).not.toBeInTheDocument();
-    await waitFor(() => {
-      expect(document.activeElement).toBe(document.querySelector('#access-token'));
-    });
-    expect(mockCreateFeed).not.toHaveBeenCalled();
-  });
-
-  it('shows lean included-feed starters on empty create when creation is enabled', async () => {
-    mockUseCatalogEntries.mockReturnValue(catalogHook([faoStarter], ['fao.org/newsroom']));
-    withMemberSession('session-token');
-    render(<App />);
-
-    await waitFor(() => {
-      expect(screen.getByRole('link', { name: 'FAO Newsroom' })).toHaveAttribute(
-        'href',
-        '/fao.org/newsroom.rss'
-      );
-    });
-    const starters = screen.getByRole('status');
-    expect(starters.querySelector('.ui-eyebrow')?.textContent).toBe(COPY.feedDirectory);
-    expect(screen.queryByText(COPY.feedDirectoryIntro)).not.toBeInTheDocument();
-    expect(screen.queryByText(COPY.feedDirectoryLearnMore)).not.toBeInTheDocument();
-    expect(document.querySelector('.notice')).toBeNull();
-    expect(screen.getByRole('list', { name: COPY.feedDirectory })).toBeInTheDocument();
-    const directoryLinks = screen.getAllByRole('link', { name: COPY.browseFeedDirectory(1) });
-    expect(directoryLinks).toHaveLength(2);
-    for (const link of directoryLinks) {
-      expect(link).toHaveAttribute('href', DIRECTORY_HREF);
-      expect(link).toHaveClass('utility-link');
-    }
-    await waitFor(() => {
-      expect(document.activeElement).toBe(screen.getByLabelText(COPY.urlLabel));
-    });
-  });
-
-  it('hides included-feed starters when the URL field is non-empty', async () => {
-    mockUseCatalogEntries.mockReturnValue(catalogHook([faoStarter], ['fao.org/newsroom']));
-    withMemberSession('session-token');
-    render(<App />);
-
-    await waitFor(() => {
-      expect(screen.getByRole('link', { name: 'FAO Newsroom' })).toBeInTheDocument();
-    });
-    fillUrl('example.com/articles');
-
-    expect(screen.queryByRole('link', { name: 'FAO Newsroom' })).not.toBeInTheDocument();
-    expect(screen.queryByRole('list', { name: COPY.feedDirectory })).not.toBeInTheDocument();
-    expect(screen.getByRole('link', { name: COPY.browseFeedDirectory(1) })).toHaveAttribute(
-      'href',
-      DIRECTORY_HREF
-    );
-  });
-
-  it('hides included-feed starters when catalog find has hits', async () => {
-    mockUseCatalogEntries.mockReturnValue(catalogHook([faoStarter, anthropicNews]));
-    withMemberSession('session-token');
-    render(<App />);
-
-    await waitFor(() => {
-      expect(screen.getByRole('link', { name: 'FAO Newsroom' })).toBeInTheDocument();
-    });
-    fillUrl('www.anthropic.com/news');
-
-    await waitFor(() => {
-      expect(screen.getByRole('option', { name: 'Anthropic — News' })).toBeInTheDocument();
-    });
-    expect(screen.queryByRole('link', { name: 'FAO Newsroom' })).not.toBeInTheDocument();
-    expect(screen.queryByRole('list', { name: COPY.feedDirectory })).not.toBeInTheDocument();
-    expect(screen.getByRole('link', { name: COPY.browseFeedDirectory(2) })).toBeInTheDocument();
-  });
-
-  it('promotes included feeds when feed creation is disabled', async () => {
-    mockUseCatalogEntries.mockReturnValue(catalogHook([faoStarter], ['fao.org/newsroom']));
-    stubMetadata({ creationEnabled: false, tokenRequired: false });
-    render(<App />);
-
-    await waitFor(() => {
-      expect(document.querySelector('.notice__title')?.textContent).toBe(COPY.feedDirectory);
-    });
-    expect(screen.getByRole('link', { name: 'FAO Newsroom' })).toHaveAttribute(
-      'href',
-      '/fao.org/newsroom.rss'
-    );
-    expect(screen.getByText(COPY.creationDisabled)).toBeInTheDocument();
-    expect(screen.getByText(COPY.feedDirectoryIntro)).toBeInTheDocument();
-    expect(screen.getByRole('link', { name: COPY.feedDirectoryLearnMore })).toHaveAttribute(
-      'href',
-      'https://html2rss.github.io/web-application/guides/use-the-feed-directory/'
-    );
-    expect(document.querySelector('.notice')).not.toBeNull();
-  });
-
-  it('suggests included feeds when the URL matches the catalog', async () => {
-    mockUseCatalogEntries.mockReturnValue(catalogHook([anthropicNews]));
-    render(<App />);
-    fillUrl('www.anthropic.com/news');
-
-    await waitFor(() => {
-      expect(screen.getByRole('option', { name: 'Anthropic — News' })).toHaveAttribute(
-        'href',
-        '/anthropic.com/news.rss'
-      );
-    });
-    expect(screen.getByRole('status')).toHaveTextContent(COPY.catalogFindHint);
-  });
-
-  it('lists multiple catalog find hits for a text query including defaults href', async () => {
-    mockUseCatalogEntries.mockReturnValue(catalogHook([bbcMundo, bbcSounds]));
-    render(<App />);
-    fillUrl('bbc');
-
-    await waitFor(() => {
-      expect(screen.getByRole('option', { name: 'BBC — Mundo' })).toHaveAttribute(
-        'href',
-        '/bbc.com/mundo.rss'
-      );
-      expect(screen.getByRole('option', { name: 'BBC Sounds — Programme episodes' })).toHaveAttribute(
-        'href',
-        '/bbc.co.uk/available_episodes.rss?id=b006wkfp'
-      );
-    });
-    expect(screen.getByRole('option', { name: 'BBC — Mundo' })).toHaveClass('catalog-hit');
-    expect(screen.getByRole('option', { name: 'BBC — Mundo' })).not.toHaveClass('ui-card');
-    expect(screen.getByRole('listbox', { name: COPY.catalogFindHitsLabel })).toBeInTheDocument();
-  });
-
-  it('opens the active catalog hit with ArrowDown then Enter without submitting Create', async () => {
-    const assignSpy = vi.fn();
-    vi.stubGlobal('location', { ...location, assign: assignSpy });
-    mockUseCatalogEntries.mockReturnValue(catalogHook([bbcMundo, bbcSounds]));
-    render(<App />);
-
-    const urlField = screen.getByLabelText(COPY.urlLabel);
-    fireEvent.input(urlField, { target: { value: 'bbc' } });
-    await waitFor(() => {
-      expect(screen.getByRole('listbox', { name: COPY.catalogFindHitsLabel })).toBeInTheDocument();
-    });
-    fireEvent.keyDown(urlField, { key: 'ArrowDown' });
-    await waitFor(() => {
-      expect(urlField).toHaveAttribute('aria-activedescendant', 'catalog-find-hits-option-0');
-    });
-    fireEvent.keyDown(urlField, { key: 'Enter' });
-
-    expect(assignSpy).toHaveBeenCalledWith('/bbc.co.uk/available_episodes.rss?id=b006wkfp');
-    expect(mockCreateFeed).not.toHaveBeenCalled();
-    vi.unstubAllGlobals();
-  });
-
-  it('submits Create with Enter when no catalog hit is active', async () => {
-    withMemberSession();
-    mockUseCatalogEntries.mockReturnValue(catalogHook([bbcMundo]));
-    render(<App />);
-
-    const urlField = screen.getByLabelText(COPY.urlLabel);
-    fireEvent.input(urlField, { target: { value: 'https://www.bbc.com/mundo' } });
-    await waitFor(() => {
-      expect(screen.getByRole('listbox', { name: COPY.catalogFindHitsLabel })).toBeInTheDocument();
-    });
-    fireEvent.keyDown(urlField, { key: 'Enter' });
-
-    await waitFor(() => {
-      expect(mockCreateFeed).toHaveBeenCalledWith('https://www.bbc.com/mundo', 'saved-token');
-    });
-  });
-
-  it('renders the result panel when a feed is available', async () => {
-    history.replaceState({}, '', 'http://localhost:3000/#/result/example-token');
-    stubCreation({
-      result: {
-        feed: {
-          id: 'feed-123',
-          name: 'Example Feed',
-          url: EXAMPLE_URL,
-          feed_token: 'example-token',
-          public_url: '/api/v1/feeds/example-token',
-          json_public_url: '/api/v1/feeds/example-token.json',
-        },
-        preview: {
-          status: 'preview_failed' as const,
-          items: [],
-          isLoading: false,
-        },
-        warnings: [
-          {
-            code: 'preview_unavailable',
-            message: 'Preview unavailable right now.',
-            retryable: false,
-            nextAction: 'none',
-          },
-        ],
-      },
-    });
-    render(<App />);
-
-    expect(document.querySelector('.result-shell')).toHaveAttribute('data-state', 'result');
-    expect(screen.getByRole('button', { name: COPY.createAnother })).toBeInTheDocument();
-    expect(screen.getByRole('link', { name: COPY.openFeed })).toBeInTheDocument();
-    expect(screen.getByRole('link', { name: COPY.bookmarkletTitle })).toBeInTheDocument();
-    expect(screen.getByText('Example Feed')).toBeInTheDocument();
-    expect(screen.getByText(COPY.feedReady)).toBeInTheDocument();
-    expect(screen.getByText(COPY.previewUnavailable)).toBeInTheDocument();
-    expect(screen.getByLabelText(COPY.utilities)).toBeInTheDocument();
-
-    fireEvent.click(screen.getByRole('button', { name: COPY.createAnother }));
-    await waitFor(() => {
-      expect(location.hash).toMatch(/^#\/create/);
-    });
-  });
-
-  it('surfaces creation errors to the user', () => {
-    stubCreation({ error: serverError('Access denied') });
-    render(<App />);
-
-    expect(document.querySelector('.form-shell')).toHaveAttribute('data-state', 'error');
-    expect(screen.getByText(COPY.createFailedRetryTitle)).toBeInTheDocument();
-    expect(screen.getByText('Access denied')).toBeInTheDocument();
-  });
-
-  it('presents classified create errors with the wire sentence', () => {
-    stubCreation({
-      error: {
-        kind: 'input',
-        code: 'BLOCKED_SURFACE',
-        retryable: false,
-        nextAction: 'correct_input',
-        retryAction: 'none',
-        message: 'This site blocked automated access. Try another URL or site.',
-      },
-    });
-    render(<App />);
-
-    expect(screen.getByText(COPY.createFailedTitle)).toBeInTheDocument();
-    expect(
-      screen.getByText('This site blocked automated access. Try another URL or site.')
-    ).toBeInTheDocument();
-    expect(screen.queryByRole('button', { name: COPY.tryAgain })).not.toBeInTheDocument();
-  });
-
-  it('shows instance metadata failure as a banner without create-error chrome', () => {
-    stubMetadata({ error: 'Instance unavailable.' });
-    render(<App />);
-
-    expect(screen.getByText(COPY.instanceMetadataUnavailable)).toBeInTheDocument();
-    expect(screen.getByText(COPY.instanceUnavailable)).toBeInTheDocument();
-    expect(screen.queryByText(COPY.accessTokenUnavailable)).not.toBeInTheDocument();
-    expect(screen.queryByText(COPY.createFailedTitle)).not.toBeInTheDocument();
-    expect(document.querySelector('.form-shell')).toHaveAttribute('data-state', 'create');
-  });
-
-  it('shows access token load failure with a token title, not metadata heading', () => {
-    stubAccessToken({ error: COPY.unableToLoadToken });
-    render(<App />);
-
-    expect(screen.getByText(COPY.accessTokenUnavailable)).toBeInTheDocument();
-    expect(screen.getByText(COPY.unableToLoadToken)).toBeInTheDocument();
-    expect(screen.queryByText(COPY.instanceMetadataUnavailable)).not.toBeInTheDocument();
-    expect(screen.queryByText(COPY.createFailedTitle)).not.toBeInTheDocument();
-  });
-
-  it('shows title-only creating notice without preview copy', () => {
-    stubCreation({ isCreating: true });
-    render(<App />);
-
-    expect(screen.getByText(COPY.creating)).toBeInTheDocument();
-    expect(screen.queryByText(COPY.previewChecking)).not.toBeInTheDocument();
-  });
-
-  it('keeps the token dialog open while creating', () => {
-    stubCreation({ isCreating: true });
-    history.replaceState({}, '', 'http://localhost:3000/#/token?url=https%3A%2F%2Fexample.com%2Farticles');
-    render(<App />);
-
-    expect(document.querySelector('dialog')).toHaveAttribute('open');
-    expect(screen.getByRole('button', { name: COPY.creating })).toBeInTheDocument();
-    expect(screen.queryByText(COPY.createFailedTitle)).not.toBeInTheDocument();
-  });
-
-  it('clears stored token and keeps Docker Hub before logout in utilities', () => {
-    withMemberSession();
-    render(<App />);
-
-    const utilityItems = [
-      ...screen
-        .getByLabelText(COPY.utilities)
-        .querySelectorAll(':scope .utility-strip__items > a, :scope .utility-strip__items > button'),
-    ].map((element) => element.textContent);
-    expect(utilityItems).toEqual([
-      COPY.browseFeedDirectory(),
-      COPY.bookmarkletTitle,
-      COPY.logout,
-      COPY.dockerInstall,
-      COPY.openapiSpec,
-      COPY.sourceCode,
-    ]);
-
-    fireEvent.click(screen.getByRole('button', { name: COPY.logout }));
-    expect(mockClearToken).toHaveBeenCalled();
-  });
-
-  it('saves access token and resumes feed creation from the inline prompt', async () => {
-    render(<App />);
-    fillUrl();
-    clickCreate();
-    const accessTokenInput = document.querySelector('#access-token') as HTMLInputElement;
-    fireEvent.input(accessTokenInput, { target: { value: 'token-123' } });
-    fireEvent.click(screen.getByRole('button', { name: COPY.saveAndContinue }));
-
-    await waitFor(() => {
-      expect(mockSaveToken).toHaveBeenCalledWith('token-123');
-      expect(mockCreateFeed).toHaveBeenCalledWith(EXAMPLE_URL, 'token-123');
-    });
-  });
-
-  it('reopens the token prompt when a saved token is rejected', async () => {
-    withMemberSession();
-    mockCreateFeed.mockRejectedValueOnce(
-      Object.assign(new Error('Unauthorized'), {
-        code: 'UNAUTHORIZED',
-        status: 401,
-        kind: 'auth',
-      })
-    );
-    render(<App />);
-    fillUrl();
-    clickCreate();
-
-    await waitFor(() => {
-      expect(screen.getByRole('heading', { name: COPY.tokenTitle })).toBeInTheDocument();
-      expect(screen.getByText(COPY.tokenRejected)).toBeInTheDocument();
-      expect(mockClearToken).toHaveBeenCalled();
-      expect(mockClearCreationError).toHaveBeenCalled();
-    });
-  });
-
-  it('clears stale creation error when backing out of the token gate', async () => {
-    withMemberSession();
-    mockCreateFeed.mockRejectedValueOnce(
-      Object.assign(new Error('Unauthorized'), {
-        code: 'UNAUTHORIZED',
-        status: 401,
-        kind: 'auth',
-      })
-    );
-    render(<App />);
-    fillUrl();
-    clickCreate();
-
-    await screen.findByText(COPY.tokenRejected);
-    fireEvent.click(screen.getByRole('button', { name: COPY.back }));
-
-    await waitFor(() => {
-      expect(location.hash).toMatch(/^#\/create/);
-    });
-    expect(screen.queryByText(COPY.createFailedTitle)).not.toBeInTheDocument();
-    expect(screen.queryByText('Unauthorized')).not.toBeInTheDocument();
-  });
-
-  it('submits the token prompt with Enter', async () => {
-    render(<App />);
-    fillUrl();
-    clickCreate();
-    const accessTokenInput = document.querySelector('#access-token') as HTMLInputElement;
-    fireEvent.input(accessTokenInput, { target: { value: 'token-123' } });
-    fireEvent.keyDown(accessTokenInput, { key: 'Enter' });
-
-    await waitFor(() => {
-      expect(mockSaveToken).toHaveBeenCalledWith('token-123');
-    });
-  });
-
-  it('builds a bookmarklet that returns to the root app entry', () => {
-    render(<App />);
-    const bookmarklet = screen.getByRole('link', { name: COPY.bookmarkletTitle });
-    expect(bookmarklet.getAttribute('href')).toContain('/#/create?url=');
-    expect(bookmarklet.getAttribute('href')).not.toContain('%27+encodeURIComponent');
-  });
-
-  it('opens token entry immediately for bookmarklet urls when no token is saved', async () => {
-    history.replaceState({}, '', 'http://localhost:3000/?url=example.com%2Farticles');
-    render(<App />);
-
-    await screen.findByRole('heading', { name: COPY.tokenTitle });
-    expect(location.hash).toMatch(/^#\/token/);
-    expect(document.querySelector('dialog')).toHaveAttribute('open');
-    expect(screen.getByLabelText(COPY.urlLabel)).toBeInTheDocument();
-    await waitFor(() => {
-      expect(screen.getByLabelText(COPY.urlLabel)).toHaveValue(EXAMPLE_URL);
-    });
-    expect(mockCreateFeed).not.toHaveBeenCalled();
-  });
-
-  it('prefills the URL field when landing with a bookmarklet hash route', async () => {
-    history.replaceState({}, '', 'http://localhost:3000/#/create?url=https%3A%2F%2Fexample.com%2Farticles');
-    render(<App />);
-
-    await waitFor(() => {
-      expect(screen.getByLabelText(COPY.urlLabel)).toHaveValue(EXAMPLE_URL);
-    });
-  });
-
-  it('prefers bookmarklet route prefill over a saved draft url', async () => {
-    localStorage.setItem(
-      'html2rss_feed_draft_state',
-      JSON.stringify({ url: 'https://old.example.com/page' })
-    );
-    history.replaceState({}, '', 'http://localhost:3000/#/create?url=https%3A%2F%2Fexample.com%2Farticles');
-    render(<App />);
-
-    await waitFor(() => {
-      expect(screen.getByLabelText(COPY.urlLabel)).toHaveValue(EXAMPLE_URL);
-    });
-  });
-
-  it('shows generic retry action for alternate retry metadata and reruns create', async () => {
-    stubCreation({ error: serverError('Browserless failed.', 'alternate') });
-    withMemberSession();
-    render(<App />);
-    fillUrl();
-    fireEvent.click(screen.getByRole('button', { name: COPY.tryAgain }));
-
-    expect(screen.queryByRole('button', { name: /Retry with .*/ })).not.toBeInTheDocument();
-    await waitFor(() => {
-      expect(mockCreateFeed).toHaveBeenCalledWith(EXAMPLE_URL, 'saved-token');
-    });
-  });
-
-  it('shows Try again for primary retry metadata and reruns the create flow', async () => {
-    stubCreation({ error: serverError('Browserless failed.') });
-    withMemberSession();
-    render(<App />);
-    fillUrl();
-    fireEvent.click(screen.getByRole('button', { name: COPY.tryAgain }));
-
-    await waitFor(() => {
-      expect(mockCreateFeed).toHaveBeenCalledWith(EXAMPLE_URL, 'saved-token');
-    });
-  });
-
-  it('does not treat non-token forbidden failures as token rejection', async () => {
-    stubCreation({
-      error: {
-        kind: 'server',
-        code: 'FORBIDDEN',
-        retryable: false,
-        nextAction: 'none',
-        retryAction: 'none',
-        message: 'URL not allowed for this account',
-      },
-    });
-    withMemberSession();
-    render(<App />);
-
-    await screen.findByText('URL not allowed for this account');
-    expect(mockClearToken).not.toHaveBeenCalled();
-    expect(screen.queryByRole('heading', { name: COPY.tokenTitle })).not.toBeInTheDocument();
-    expect(screen.queryByText(COPY.tokenRejected)).not.toBeInTheDocument();
-    expect(screen.queryByRole('button', { name: COPY.tryAgain })).not.toBeInTheDocument();
-    expect(screen.queryByRole('button', { name: /Retry with .*/ })).not.toBeInTheDocument();
-  });
-
-  it('keeps extraction-empty failures generic and input-corrective', async () => {
-    stubCreation({
-      error: {
-        kind: 'input',
-        code: 'NO_FEED_ITEMS_EXTRACTED',
-        retryable: false,
-        nextAction: 'correct_input',
-        retryAction: 'none',
-        message: 'Could not extract feed items. Try a more specific listing URL or explicit selectors.',
-      },
-    });
-    withMemberSession();
-    render(<App />);
-
-    await screen.findByText(
-      'Could not extract feed items. Try a more specific listing URL or explicit selectors.'
-    );
-    expect(screen.getByText(COPY.createFailedTitle)).toBeInTheDocument();
-    expect(screen.queryByText(COPY.createFailedRetryTitle)).not.toBeInTheDocument();
-    expect(screen.queryByRole('heading', { name: COPY.tokenTitle })).not.toBeInTheDocument();
-    expect(screen.queryByRole('button', { name: COPY.tryAgain })).not.toBeInTheDocument();
-    expect(mockClearToken).not.toHaveBeenCalled();
-  });
-
-  it('returns non-auth token save failures onto create with notice', async () => {
-    mockCreateFeed.mockRejectedValueOnce(serverError('Upstream failed'));
-    render(<App />);
-    fillUrl();
-    clickCreate();
-    const accessTokenInput = document.querySelector('#access-token') as HTMLInputElement;
-    fireEvent.input(accessTokenInput, { target: { value: 'token-123' } });
-    fireEvent.click(screen.getByRole('button', { name: COPY.saveAndContinue }));
-
-    await waitFor(() => {
-      expect(location.hash).toMatch(/^#\/create/);
-    });
-    expect(document.querySelector('dialog')).toBeNull();
-    expect(screen.getByText(COPY.createFailedRetryTitle)).toBeInTheDocument();
-    expect(screen.getByText('Upstream failed')).toBeInTheDocument();
-  });
-
-  it('cancels the token dialog with Back, Escape, and backdrop', async () => {
-    render(<App />);
-    fillUrl();
-    clickCreate();
-
-    expect(document.querySelector('dialog')).toHaveAttribute('open');
-    const accessTokenInput = document.querySelector('#access-token') as HTMLInputElement;
-    fireEvent.input(accessTokenInput, { target: { value: 'secret-draft' } });
-    fireEvent.click(screen.getByRole('button', { name: COPY.back }));
-
-    await waitFor(() => {
-      expect(location.hash).toMatch(/^#\/create/);
-    });
-    expect(document.querySelector('dialog')).toBeNull();
-
-    clickCreate();
-    const dialog = document.querySelector('dialog');
-    expect(dialog).toHaveAttribute('open');
-    expect((document.querySelector('#access-token') as HTMLInputElement).value).toBe('');
-    fireEvent(dialog as HTMLDialogElement, new Event('cancel', { bubbles: true }));
-
-    await waitFor(() => {
-      expect(location.hash).toMatch(/^#\/create/);
-    });
-
-    clickCreate();
-    const openDialog = document.querySelector('dialog') as HTMLDialogElement;
-    expect(openDialog).toHaveAttribute('open');
-    fireEvent.click(openDialog);
-
-    await waitFor(() => {
-      expect(location.hash).toMatch(/^#\/create/);
-    });
-    expect(document.querySelector('dialog')).toBeNull();
-  });
-
-  it('shows the utility links in a user-focused order', () => {
-    render(<App />);
-
-    const utilityLinks = [
-      ...screen.getByLabelText(COPY.utilities).querySelectorAll(':scope .utility-strip__items > a'),
-    ].map((link) => link.textContent);
-    expect(utilityLinks).toEqual([
-      COPY.browseFeedDirectory(),
-      COPY.bookmarkletTitle,
-      COPY.dockerInstall,
-      COPY.openapiSpec,
-      COPY.sourceCode,
-    ]);
-    expect(screen.getByRole('link', { name: COPY.openapiSpec })).toHaveAttribute(
-      'href',
-      'https://example.test/openapi.yaml'
-    );
-    expect(screen.getByRole('link', { name: COPY.browseFeedDirectory() })).toHaveAttribute(
-      'href',
-      DIRECTORY_HREF
-    );
-    expect(screen.getByRole('link', { name: COPY.dockerInstall })).toHaveAttribute(
-      'href',
-      'https://hub.docker.com/r/html2rss/web'
-    );
-  });
-
-  it('keeps OpenAPI link on the frontend origin during local development', () => {
-    stubMetadata({ openapiUrl: 'http://127.0.0.1:4000/openapi.yaml' });
-    render(<App />);
-
-    expect(screen.getByRole('link', { name: COPY.openapiSpec })).toHaveAttribute(
-      'href',
-      'http://localhost:3000/openapi.yaml'
-    );
-  });
-});
diff --git a/frontend/src/__tests__/mocks/apiFixtures.ts b/frontend/src/__tests__/mocks/apiFixtures.ts
index f592f738..93cf51ea 100644
--- a/frontend/src/__tests__/mocks/apiFixtures.ts
+++ b/frontend/src/__tests__/mocks/apiFixtures.ts
@@ -39,6 +39,43 @@ export const emptyCatalog = {
   meta: { total: 0, catalog_version: 2, starters: [] },
 };
 
+export type CatalogWireEntry = {
+  id: string;
+  path?: string;
+  channelUrl: string;
+  title: string;
+  summary?: string;
+  parameterDefaults?: Record<string, string>;
+  lastResultState?: string;
+};
+
+export function catalogWireEntry({
+  id,
+  path,
+  channelUrl,
+  title,
+  summary,
+  parameterDefaults = {},
+  lastResultState = 'unknown',
+}: CatalogWireEntry) {
+  return {
+    id,
+    path: path ?? `/${id}.rss`,
+    channel: { url: channelUrl },
+    directory: { title, summary: summary ?? `${title} description.` },
+    parameters: { schema: {}, defaults: parameterDefaults },
+    last_result: { state: lastResultState },
+  };
+}
+
+export function catalogBody(entries: ReturnType<typeof catalogWireEntry>[], starters: string[] = []) {
+  return {
+    success: true,
+    data: { configs: entries },
+    meta: { total: entries.length, catalog_version: 2, starters },
+  };
+}
+
 export type CreatedFeedOverrides = {
   id?: string;
   name?: string;

From 1710f32d4fca39e3de0d317eebbc765744e0f56b Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Tue, 22 Sep 2026 00:00:12 +0200
Subject: [PATCH 101/108] test(frontend): drop hook suites that repeat the App
 journey

---
 frontend/src/__tests__/useFeedFlow.test.ts | 366 ---------------------
 frontend/src/__tests__/useSession.test.ts  | 243 --------------
 2 files changed, 609 deletions(-)
 delete mode 100644 frontend/src/__tests__/useFeedFlow.test.ts
 delete mode 100644 frontend/src/__tests__/useSession.test.ts

diff --git a/frontend/src/__tests__/useFeedFlow.test.ts b/frontend/src/__tests__/useFeedFlow.test.ts
deleted file mode 100644
index 46485725..00000000
--- a/frontend/src/__tests__/useFeedFlow.test.ts
+++ /dev/null
@@ -1,366 +0,0 @@
-import { describe, it, expect, beforeEach, afterEach, vi, type SpyInstance } from 'vitest';
-import { renderHook, act, waitFor } from '@testing-library/preact';
-import { useFeedFlow, type FeedFlowDependencies } from '../feed';
-
-const mockFeed = {
-  id: 'feed-1',
-  name: 'Example Feed',
-  url: 'https://example.com/articles',
-  feed_token: 'feed-token-1',
-  public_url: '/api/v1/feeds/feed-token-1',
-  json_public_url: '/api/v1/feeds/feed-token-1.json',
-  created_at: '2024-01-01T00:00:00Z',
-  updated_at: '2024-01-01T00:00:00Z',
-};
-
-async function stubFeedCreationFailure(message = 'Upstream failed') {
-  const { server, buildStructuredErrorResponse } = await import('./mocks/server');
-  const { http, HttpResponse } = await import('msw');
-  server.use(
-    http.post('/api/v1/feeds', () =>
-      HttpResponse.json(
-        buildStructuredErrorResponse({
-          message,
-          kind: 'server',
-          retryable: true,
-          next_action: 'retry',
-          retry_action: 'primary',
-        }),
-        { status: 500 }
-      )
-    )
-  );
-}
-
-describe('useFeedFlow', () => {
-  let fetchMock: SpyInstance;
-  const mockNavigate = vi.fn();
-  const mockSaveToken = vi.fn();
-  const mockClearToken = vi.fn();
-
-  const feedFlowProperties = (overrides: Partial<FeedFlowDependencies> = {}): FeedFlowDependencies => ({
-    token: undefined,
-    isLoading: false,
-    feedCreationEnabled: true,
-    mayCreate: () => 'proceed',
-    saveToken: mockSaveToken,
-    clearToken: mockClearToken,
-    route: { kind: 'create' },
-    navigate: mockNavigate,
-    createEntryKey: 0,
-    ...overrides,
-  });
-
-  beforeEach(() => {
-    vi.clearAllMocks();
-    localStorage.clear();
-    sessionStorage.clear();
-    fetchMock = vi.spyOn(globalThis, 'fetch');
-  });
-
-  afterEach(() => {
-    fetchMock.mockRestore();
-  });
-
-  it('prefills the url field from route prefill even when a draft url exists', async () => {
-    localStorage.setItem(
-      'html2rss_feed_draft_state',
-      JSON.stringify({ url: 'https://old.example.com/page' })
-    );
-
-    const { result } = renderHook(() =>
-      useFeedFlow(
-        feedFlowProperties({
-          route: { kind: 'create', prefillUrl: 'https://example.com/articles' },
-        })
-      )
-    );
-
-    await waitFor(() => {
-      expect(result.current.feedFormData.url).toBe('https://example.com/articles');
-    });
-  });
-
-  it('manages form input field changes and draft state', async () => {
-    const { result } = renderHook(() => useFeedFlow(feedFlowProperties()));
-
-    act(() => {
-      result.current.onFeedFieldChange('url', 'https://example.com/new-articles');
-    });
-
-    expect(result.current.feedFormData.url).toBe('https://example.com/new-articles');
-    expect(JSON.parse(localStorage.getItem('html2rss_feed_draft_state') || '{}').url).toBe(
-      'https://example.com/new-articles'
-    );
-  });
-
-  it('performs validation and creates feed on submit when no token is required', async () => {
-    fetchMock
-      .mockResolvedValueOnce(Response.json({ success: true, data: { feed: mockFeed } }))
-      .mockResolvedValueOnce(Response.json({ items: [] }));
-
-    const { result } = renderHook(() => useFeedFlow(feedFlowProperties()));
-
-    act(() => {
-      result.current.onFeedFieldChange('url', 'https://example.com/new-articles');
-    });
-
-    const event = { preventDefault: vi.fn() } as any;
-    await act(async () => {
-      await result.current.onFeedSubmit(event);
-    });
-
-    expect(fetchMock).toHaveBeenCalled();
-    expect(mockNavigate).toHaveBeenCalledWith({ kind: 'result', feedToken: 'feed-token-1' });
-  });
-
-  it('redirects to token route when token is required but missing', async () => {
-    const { result } = renderHook(() =>
-      useFeedFlow(
-        feedFlowProperties({
-          mayCreate: () => 'needToken',
-        })
-      )
-    );
-
-    act(() => {
-      result.current.onFeedFieldChange('url', 'https://example.com/private-articles');
-    });
-
-    const event = { preventDefault: vi.fn() } as any;
-    await act(async () => {
-      await result.current.onFeedSubmit(event);
-    });
-
-    expect(fetchMock).not.toHaveBeenCalled();
-    expect(mockNavigate).toHaveBeenCalledWith({
-      kind: 'token',
-      prefillUrl: 'https://example.com/private-articles',
-    });
-  });
-
-  it('navigates to token and projects token_prompt on auth creation failure', async () => {
-    const { server, buildStructuredErrorResponse } = await import('./mocks/server');
-    const { http, HttpResponse } = await import('msw');
-    server.use(
-      http.post('/api/v1/feeds', () =>
-        HttpResponse.json(
-          buildStructuredErrorResponse({
-            message: 'Access denied',
-            kind: 'auth',
-            code: 'UNAUTHORIZED',
-            retryable: false,
-            next_action: 'enter_token',
-            retry_action: 'none',
-          }),
-          { status: 401 }
-        )
-      )
-    );
-
-    const { result, rerender } = renderHook(
-      ({ route }) =>
-        useFeedFlow(feedFlowProperties({ route, mayCreate: () => 'proceed', token: 'bad-token' })),
-      { initialProps: { route: { kind: 'create' as const } } }
-    );
-
-    act(() => {
-      result.current.onFeedFieldChange('url', 'https://example.com/private-articles');
-    });
-
-    await act(async () => {
-      await result.current.onFeedSubmit({ preventDefault: vi.fn() } as any);
-    });
-
-    expect(mockNavigate).toHaveBeenCalledWith({
-      kind: 'token',
-      prefillUrl: 'https://example.com/private-articles',
-    });
-    expect(mockClearToken).toHaveBeenCalled();
-
-    rerender({ route: { kind: 'token', prefillUrl: 'https://example.com/private-articles' } });
-
-    expect(result.current.viewModel.kind).toBe('token_prompt');
-    expect(result.current.tokenError).toBeTruthy();
-  });
-
-  it('returns non-auth creation failures from token onto create', async () => {
-    await stubFeedCreationFailure();
-
-    const { result, rerender } = renderHook(
-      ({ route }) =>
-        useFeedFlow(
-          feedFlowProperties({
-            mayCreate: () => 'proceed',
-            route,
-          })
-        ),
-      {
-        initialProps: {
-          route: { kind: 'token' as const, prefillUrl: 'https://example.com/private-articles' },
-        },
-      }
-    );
-
-    act(() => {
-      result.current.onFeedFieldChange('url', 'https://example.com/private-articles');
-      result.current.setTokenDraft('token-123');
-    });
-
-    mockSaveToken.mockResolvedValueOnce(undefined);
-
-    await act(async () => {
-      await result.current.onSaveToken();
-    });
-
-    expect(mockNavigate).toHaveBeenCalledWith({
-      kind: 'create',
-      prefillUrl: 'https://example.com/private-articles',
-    });
-    expect(result.current.tokenError).toBe('');
-    expect(result.current.feedFieldErrors.form).toBe('Upstream failed');
-    expect(result.current.creationError).toMatchObject({
-      message: 'Upstream failed',
-      nextAction: 'retry',
-    });
-
-    // Simulate router applying token→create; remount must keep Decision error for retry chrome.
-    rerender({
-      route: { kind: 'create', prefillUrl: 'https://example.com/private-articles' },
-    });
-
-    expect(result.current.feedFieldErrors.form).toBe('Upstream failed');
-    expect(result.current.creationError).toMatchObject({
-      message: 'Upstream failed',
-      nextAction: 'retry',
-    });
-  });
-
-  it('recovers unmatched result routes onto remounted create without prefillUrl', async () => {
-    const { result, rerender } = renderHook(
-      ({ route, createEntryKey }) => useFeedFlow(feedFlowProperties({ route, createEntryKey })),
-      { initialProps: { route: { kind: 'result' as const, feedToken: 'missing-token' }, createEntryKey: 0 } }
-    );
-
-    await waitFor(() => {
-      expect(mockNavigate).toHaveBeenCalledWith({ kind: 'create' }, { replace: true });
-    });
-
-    for (const [route] of mockNavigate.mock.calls) {
-      if (route.kind !== 'create') continue;
-      expect(route).toEqual({ kind: 'create' });
-      expect(route).not.toHaveProperty('prefillUrl');
-    }
-
-    rerender({ route: { kind: 'create' }, createEntryKey: 0 });
-
-    expect(result.current.focusCreateComposerKey).toBeGreaterThan(0);
-    expect(result.current.creationError).toBeUndefined();
-  });
-
-  it('aligns the result hash with an in-memory feed when studio generate advances the token', async () => {
-    const refinedFeed = {
-      ...mockFeed,
-      feed_token: 'feed-token-2',
-      public_url: '/api/v1/feeds/feed-token-2',
-      json_public_url: '/api/v1/feeds/feed-token-2.json',
-    };
-
-    fetchMock
-      .mockResolvedValueOnce(Response.json({ success: true, data: { feed: mockFeed } }))
-      .mockResolvedValueOnce(Response.json({ items: [] }))
-      .mockResolvedValueOnce(Response.json({ success: true, data: { feed: refinedFeed } }))
-      .mockResolvedValueOnce(Response.json({ items: [] }));
-
-    const { result, rerender } = renderHook(
-      ({ route }) =>
-        useFeedFlow(
-          feedFlowProperties({
-            route,
-            token: 'access-token',
-            mayCreate: () => 'proceed',
-          })
-        ),
-      { initialProps: { route: { kind: 'create' as const } } }
-    );
-
-    act(() => {
-      result.current.onFeedFieldChange('url', 'https://example.com/articles');
-    });
-    await act(async () => {
-      await result.current.onFeedSubmit({ preventDefault: vi.fn() } as any);
-    });
-
-    mockNavigate.mockClear();
-    rerender({ route: { kind: 'result', feedToken: 'feed-token-1' } });
-
-    await act(async () => {
-      await result.current.generateFromStudio({ items: { selector: 'article' } });
-    });
-
-    expect(mockNavigate).not.toHaveBeenCalledWith({ kind: 'create' }, expect.anything());
-    expect(mockNavigate).not.toHaveBeenCalledWith({ kind: 'create' });
-    expect(mockNavigate).toHaveBeenCalledWith({ kind: 'result', feedToken: 'feed-token-2' });
-    expect(result.current.result?.feed.feed_token).toBe('feed-token-2');
-  });
-
-  it('remounts create on a later create-entry visit and clears creation chrome', async () => {
-    await stubFeedCreationFailure();
-
-    const { result, rerender } = renderHook(
-      ({ createEntryKey }) => useFeedFlow(feedFlowProperties({ createEntryKey })),
-      { initialProps: { createEntryKey: 0 } }
-    );
-
-    act(() => {
-      result.current.onFeedFieldChange('url', 'https://example.com/articles');
-    });
-
-    await act(async () => {
-      await result.current.onFeedSubmit({ preventDefault: vi.fn() } as any);
-    });
-
-    expect(result.current.creationError).toMatchObject({ message: 'Upstream failed' });
-    expect(result.current.feedFieldErrors.form).toBe('Upstream failed');
-    const previousFocusKey = result.current.focusCreateComposerKey;
-    const fetchCallsAfterSubmit = fetchMock.mock.calls.length;
-
-    rerender({ createEntryKey: 1 });
-
-    expect(result.current.creationError).toBeUndefined();
-    expect(result.current.feedFieldErrors.form).toBe('');
-    expect(result.current.tokenError).toBe('');
-    expect(result.current.tokenDraft).toBe('');
-    expect(result.current.focusCreateComposerKey).toBeGreaterThan(previousFocusKey);
-    expect(fetchMock).toHaveBeenCalledTimes(fetchCallsAfterSubmit);
-  });
-
-  it('clears token draft on cancel and create remount', async () => {
-    const { result, rerender } = renderHook(
-      ({ createEntryKey, route }) => useFeedFlow(feedFlowProperties({ createEntryKey, route })),
-      {
-        initialProps: {
-          createEntryKey: 0,
-          route: { kind: 'token' as const, prefillUrl: 'https://example.com' },
-        },
-      }
-    );
-
-    act(() => {
-      result.current.setTokenDraft('secret-draft');
-    });
-    expect(result.current.tokenDraft).toBe('secret-draft');
-
-    act(() => {
-      result.current.onCancelTokenPrompt();
-    });
-    expect(result.current.tokenDraft).toBe('');
-    expect(mockNavigate).toHaveBeenCalledWith({ kind: 'create', prefillUrl: expect.any(String) });
-
-    act(() => {
-      result.current.setTokenDraft('another-secret');
-    });
-    rerender({ createEntryKey: 1, route: { kind: 'create' } });
-    expect(result.current.tokenDraft).toBe('');
-  });
-});
diff --git a/frontend/src/__tests__/useSession.test.ts b/frontend/src/__tests__/useSession.test.ts
deleted file mode 100644
index 337c88c9..00000000
--- a/frontend/src/__tests__/useSession.test.ts
+++ /dev/null
@@ -1,243 +0,0 @@
-import { describe, it, expect, beforeEach, afterEach, vi, type SpyInstance } from 'vitest';
-import { renderHook, act, waitFor } from '@testing-library/preact';
-import { httpRequestUrl } from '../api/http/client';
-import { resetAccessTokenMemory, useSession } from '../session';
-import { getPersistentStorage } from '../utils/persistentStorage';
-
-const ACCESS_TOKEN_KEY = 'html2rss_access_token';
-
-const mockMetadata = {
-  instance: {
-    feed_creation: { enabled: true, access_token_required: true },
-    studio: { enabled: true },
-    catalog: { enabled: true, url: '/api/v1/configs' },
-  },
-  api: { openapi_url: '/openapi.yaml' },
-};
-
-describe('useSession', () => {
-  let fetchMock: SpyInstance;
-
-  const emptyCatalogResponse = Response.json({
-    success: true,
-    data: { configs: [] },
-    meta: { total: 0, catalog_version: 2, starters: [] },
-  });
-
-  const mockFetchFor = (metadata: unknown, catalogResponse: Response = emptyCatalogResponse) => {
-    fetchMock.mockImplementation(async (input: RequestInfo | URL) => {
-      const url = httpRequestUrl(input);
-      if (url.pathname.includes('/configs')) return catalogResponse.clone();
-      return Response.json({ success: true, data: metadata });
-    });
-  };
-
-  beforeEach(() => {
-    vi.clearAllMocks();
-    getPersistentStorage().clear();
-    localStorage.clear();
-    sessionStorage.clear();
-    resetAccessTokenMemory();
-    fetchMock = vi.spyOn(globalThis, 'fetch');
-  });
-
-  afterEach(() => {
-    resetAccessTokenMemory();
-    getPersistentStorage().clear();
-    fetchMock.mockRestore();
-  });
-
-  it('coordinates api metadata load and token loading', async () => {
-    localStorage.setItem(ACCESS_TOKEN_KEY, 'session-token');
-    mockFetchFor(mockMetadata);
-
-    const { result } = renderHook(() => useSession());
-
-    expect(result.current.isLoading).toBe(true);
-
-    await waitFor(() => {
-      expect(result.current.isLoading).toBe(false);
-    });
-
-    expect(result.current.token).toBe('session-token');
-    expect(result.current.hasToken).toBe(true);
-    expect(result.current.featuredFeeds).toEqual([]);
-    expect(result.current.catalogEntries).toEqual([]);
-    expect(result.current.metadataError).toBeUndefined();
-    expect(result.current.feedCreationEnabled).toBe(true);
-  });
-
-  it('selects starter feeds when feed creation is enabled', async () => {
-    const fao = {
-      id: 'fao.org/newsroom',
-      path: '/fao.org/newsroom.rss',
-      channel: { url: 'https://www.fao.org/newsroom' },
-      directory: { title: 'FAO Newsroom', summary: 'News' },
-      parameters: { defaults: {} },
-      last_result: { state: 'unknown' },
-    };
-    mockFetchFor(
-      mockMetadata,
-      Response.json({
-        success: true,
-        data: { configs: [fao] },
-        meta: { total: 1, catalog_version: 2, starters: ['fao.org/newsroom'] },
-      })
-    );
-
-    const { result } = renderHook(() => useSession());
-    await waitFor(() => {
-      expect(result.current.featuredFeeds.map((entry) => entry.id)).toEqual(['fao.org/newsroom']);
-    });
-
-    expect(result.current.feedCreationEnabled).toBe(true);
-  });
-
-  it('saves new tokens to persistent storage and does not write sessionStorage', async () => {
-    mockFetchFor(mockMetadata);
-
-    const { result } = renderHook(() => useSession());
-    await waitFor(() => expect(result.current.isLoading).toBe(false));
-
-    await act(async () => {
-      await result.current.saveToken('brand-new-token');
-    });
-
-    expect(result.current.token).toBe('brand-new-token');
-    expect(result.current.hasToken).toBe(true);
-    expect(getPersistentStorage().getItem(ACCESS_TOKEN_KEY)).toBe('brand-new-token');
-    expect(localStorage.getItem(ACCESS_TOKEN_KEY)).toBe('brand-new-token');
-    expect(sessionStorage.getItem(ACCESS_TOKEN_KEY)).toBeNull();
-  });
-
-  it('clears the canonical persistent token copy', async () => {
-    localStorage.setItem(ACCESS_TOKEN_KEY, 'old-token');
-    mockFetchFor(mockMetadata);
-
-    const { result } = renderHook(() => useSession());
-    await waitFor(() => expect(result.current.isLoading).toBe(false));
-
-    act(() => {
-      result.current.clearToken();
-    });
-
-    expect(result.current.token).toBeUndefined();
-    expect(result.current.hasToken).toBe(false);
-    expect(getPersistentStorage().getItem(ACCESS_TOKEN_KEY)).toBeNull();
-    expect(sessionStorage.getItem(ACCESS_TOKEN_KEY)).toBeNull();
-  });
-
-  it('falls back to in-memory token when persistent storage write is unavailable', async () => {
-    mockFetchFor(mockMetadata);
-    localStorage.setItem.mockImplementationOnce(() => {
-      throw new Error('blocked');
-    });
-
-    const { result } = renderHook(() => useSession());
-    await waitFor(() => expect(result.current.isLoading).toBe(false));
-
-    await act(async () => {
-      await result.current.saveToken('memory-token');
-    });
-
-    expect(result.current.token).toBe('memory-token');
-    expect(result.current.hasToken).toBe(true);
-    expect(sessionStorage.getItem(ACCESS_TOKEN_KEY)).toBeNull();
-  });
-
-  it('loads from in-memory fallback when persistent storage read is unavailable', async () => {
-    mockFetchFor(mockMetadata);
-    localStorage.setItem.mockImplementationOnce(() => {
-      throw new Error('blocked');
-    });
-
-    const seeded = renderHook(() => useSession());
-    await waitFor(() => expect(seeded.result.current.isLoading).toBe(false));
-    await act(async () => {
-      await seeded.result.current.saveToken('memory-only');
-    });
-    seeded.unmount();
-
-    localStorage.getItem.mockImplementationOnce(() => {
-      throw new Error('blocked');
-    });
-
-    const { result } = renderHook(() => useSession());
-    await waitFor(() => expect(result.current.isLoading).toBe(false));
-
-    expect(result.current.token).toBe('memory-only');
-    expect(result.current.hasToken).toBe(true);
-    expect(sessionStorage.getItem(ACCESS_TOKEN_KEY)).toBeNull();
-  });
-
-  it('mayCreate returns needToken when access token is required and missing', async () => {
-    mockFetchFor(mockMetadata);
-
-    const { result } = renderHook(() => useSession());
-    await waitFor(() => expect(result.current.isLoading).toBe(false));
-
-    expect(result.current.mayCreate()).toBe('needToken');
-    expect(result.current.mayCreate('')).toBe('needToken');
-    expect(result.current.mayCreate('provided-token')).toBe('proceed');
-    expect(result.current.studioEnabled).toBe(true);
-  });
-
-  it('mayCreate returns disabled when feed creation is disabled', async () => {
-    mockFetchFor({
-      ...mockMetadata,
-      instance: {
-        ...mockMetadata.instance,
-        feed_creation: { enabled: false, access_token_required: true },
-      },
-    });
-
-    const { result } = renderHook(() => useSession());
-    await waitFor(() => expect(result.current.isLoading).toBe(false));
-
-    expect(result.current.feedCreationEnabled).toBe(false);
-    expect(result.current.mayCreate('any-token')).toBe('disabled');
-  });
-
-  it('mayCreate returns proceed when token is not required', async () => {
-    mockFetchFor({
-      ...mockMetadata,
-      instance: {
-        ...mockMetadata.instance,
-        feed_creation: { enabled: true, access_token_required: false },
-      },
-    });
-
-    const { result } = renderHook(() => useSession());
-    await waitFor(() => expect(result.current.isLoading).toBe(false));
-
-    expect(result.current.mayCreate()).toBe('proceed');
-  });
-
-  it('defaults gate to token-required when metadata feed_creation is absent', async () => {
-    mockFetchFor({
-      api: mockMetadata.api,
-      instance: {},
-    });
-
-    const { result } = renderHook(() => useSession());
-    await waitFor(() => expect(result.current.isLoading).toBe(false));
-
-    expect(result.current.feedCreationEnabled).toBe(true);
-    expect(result.current.mayCreate()).toBe('needToken');
-  });
-
-  it('defaults studio to disabled when metadata studio is absent', async () => {
-    mockFetchFor({
-      ...mockMetadata,
-      instance: {
-        feed_creation: { enabled: true, access_token_required: true },
-        catalog: { enabled: true, url: '/api/v1/configs' },
-      },
-    });
-
-    const { result } = renderHook(() => useSession());
-    await waitFor(() => expect(result.current.isLoading).toBe(false));
-
-    expect(result.current.studioEnabled).toBe(false);
-  });
-});

From ca7c69c21e3a8d5b43399ade930ba2b92a08e5ce Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Tue, 22 Sep 2026 00:01:41 +0200
Subject: [PATCH 102/108] test(frontend): leave useStudio on timers and
 ConfigStudio on DOM

---
 frontend/src/__tests__/ConfigStudio.test.tsx | 307 +--------
 frontend/src/__tests__/selectorDraft.test.ts |  53 +-
 frontend/src/__tests__/useStudio.test.ts     | 678 ++-----------------
 3 files changed, 154 insertions(+), 884 deletions(-)

diff --git a/frontend/src/__tests__/ConfigStudio.test.tsx b/frontend/src/__tests__/ConfigStudio.test.tsx
index 8ad55bb7..accf02d0 100644
--- a/frontend/src/__tests__/ConfigStudio.test.tsx
+++ b/frontend/src/__tests__/ConfigStudio.test.tsx
@@ -10,6 +10,7 @@ import {
   suggestSuccessBody,
   validateSuccessBody,
   validateYamlForSelectors,
+  studioPreviewSuccessBody,
 } from './mocks/apiFixtures';
 import { ConfigStudio } from '../components/ConfigStudio';
 import { COPY } from '../journey/copy';
@@ -25,36 +26,8 @@ vi.mock('../studio/useStudio', async (importOriginal) => {
 
 const pageUrl = 'https://example.com/articles';
 
-function suggestEnvelope(selector = 'article', isEnhanced = false, extras: Record<string, unknown> = {}) {
-  return suggestSuccessBody(selector, isEnhanced, extras);
-}
-
-function validateEnvelope(selectors?: unknown, report?: { success: boolean; issues: unknown[] }) {
-  return {
-    success: true,
-    data: {
-      report: report ?? { success: true, issues: [] },
-      selectors: selectors ?? { items: { selector: 'article', enhance: false } },
-      yaml: 'selectors: {}',
-    },
-  };
-}
-
-function previewEnvelope(items: Array<Record<string, unknown>>, quality?: Record<string, unknown>) {
-  return {
-    success: true,
-    data: {
-      item_count: items.length,
-      sample_items: items,
-      quality_report: quality ?? { warnings: [], metrics: { short_title_count: 0 } },
-      failure_kind: null,
-      validation_issues: [],
-    },
-  };
-}
-
-const previewWithImage = () =>
-  previewEnvelope([
+function previewWithImage() {
+  return studioPreviewSuccessBody([
     {
       title: 'With image',
       url: 'https://example.com/sample',
@@ -63,6 +36,7 @@ const previewWithImage = () =>
     },
     { title: 'No image', url: 'https://example.com/plain' },
   ]);
+}
 
 function echoValidate() {
   server.use(
@@ -75,7 +49,7 @@ function echoValidate() {
   );
 }
 
-function stubSuggest(body: unknown = suggestEnvelope()) {
+function stubSuggest(body: unknown = suggestSuccessBody()) {
   server.use(http.post('/api/v1/feeds/suggest_selectors', () => HttpResponse.json(body)));
 }
 
@@ -112,39 +86,24 @@ async function waitForItemsChip(name = COPY.addSelector('article')) {
 }
 
 describe('ConfigStudio', () => {
-  it('keeps the items selector above the preview meadow', async () => {
+  it('keeps one rail with items above the meadow and no listing URL field', async () => {
     echoValidate();
     stubPreview(previewWithImage());
     renderStudio();
 
-    fireEvent.click(await waitForItemsChip());
-    await waitFor(() => expect(screen.getByText('With image')).toBeInTheDocument());
-
-    const meadow = screen.getByLabelText(COPY.previewRegion);
-    const items = screen.getByLabelText(COPY.itemsSelector);
-    expect(items.compareDocumentPosition(meadow) & Node.DOCUMENT_POSITION_FOLLOWING).not.toBe(0);
-    expect(document.querySelector('.ui-card')).toBeNull();
-  });
-
-  it('keeps one rail starting with the items selector and no listing URL field', async () => {
-    renderStudio();
-
     const items = screen.getByLabelText(COPY.itemsSelector);
     expect(screen.queryByLabelText(COPY.urlLabel)).not.toBeInTheDocument();
     expect(document.querySelector('.refine-columns')).toBeNull();
-    expect(screen.getByRole('button', { name: COPY.saveAndGenerate })).toBeDisabled();
     expect(screen.queryByRole('combobox')).not.toBeInTheDocument();
     expect(document.querySelector('textarea')).toBeNull();
-    expect(screen.queryByText(/Cleanup/i)).not.toBeInTheDocument();
-    expect(screen.queryByText(/Strip HTML/i)).not.toBeInTheDocument();
     expect(screen.getByLabelText(COPY.enhanceItems)).toBeInTheDocument();
-    await waitFor(() => expect(itemsChip()).toBeInTheDocument());
-    expect(items.compareDocumentPosition(itemsChip()) & Node.DOCUMENT_POSITION_FOLLOWING).not.toBe(0);
-    expect(screen.getByRole('button', { name: COPY.fieldMissing(COPY.fieldTitle) })).toBeInTheDocument();
-    expect(screen.getByRole('button', { name: COPY.fieldMissing(COPY.fieldLink) })).toBeInTheDocument();
-    expect(screen.getByRole('button', { name: COPY.fieldMissing(COPY.fieldPublished) })).toBeInTheDocument();
-    expect(screen.getByText(COPY.previewFetchedCaption)).toBeInTheDocument();
-    await waitFor(() => expect(screen.getByRole('button', { name: COPY.saveAndGenerate })).toBeEnabled());
+
+    fireEvent.click(await waitForItemsChip());
+    await waitFor(() => expect(screen.getByText('With image')).toBeInTheDocument());
+
+    const meadow = screen.getByLabelText(COPY.previewRegion);
+    expect(items.compareDocumentPosition(meadow) & Node.DOCUMENT_POSITION_FOLLOWING).not.toBe(0);
+    expect(document.querySelector('.ui-card')).toBeNull();
     expect(screen.getByRole('button', { name: COPY.saveAndGenerate }).closest('.ui-actions')).not.toBeNull();
   });
 
@@ -158,7 +117,7 @@ describe('ConfigStudio', () => {
     expect(items).toHaveValue('a[href]');
     expect(screen.queryByRole('group', { name: COPY.selectorChoices })).not.toBeInTheDocument();
 
-    pendingSuggestion.resolve(HttpResponse.json(suggestEnvelope('.post', true)));
+    pendingSuggestion.resolve(HttpResponse.json(suggestSuccessBody('.post', true)));
 
     await waitFor(() => expect(screen.getByText('.post')).toBeInTheDocument());
     expect(screen.getByRole('group', { name: COPY.selectorChoices })).toBeInTheDocument();
@@ -166,135 +125,27 @@ describe('ConfigStudio', () => {
     expect(screen.getByLabelText(COPY.enhanceItems)).not.toBeChecked();
   });
 
-  it('shows ranked choices without overwriting the draft', async () => {
-    echoValidate();
-    stubSuggest(
-      rankedSuggestSuccessBody(
-        {
-          items: [
-            { selector: '.post', enhance: true },
-            { selector: 'article', enhance: false },
-          ],
-          title: [{ selector: 'h2' }],
-          link: [{ selector: 'a' }],
-          published: [{ selector: 'time' }],
-        },
-        { admission_drops: { chrome: 2 } }
-      )
-    );
-    renderStudio();
-
-    await waitFor(() => expect(screen.getByText('.post')).toBeInTheDocument());
-    expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('a[href]');
-    expect(screen.getByLabelText(COPY.enhanceItems)).not.toBeChecked();
-    expect(screen.getByText('article')).toBeInTheDocument();
-    expect(screen.getByText('h2')).toBeInTheDocument();
-    expect(screen.getByText('a')).toBeInTheDocument();
-    expect(screen.getByText('time')).toBeInTheDocument();
-    expect(screen.queryByText('list')).not.toBeInTheDocument();
-    expect(screen.queryByText(/chrome/)).not.toBeInTheDocument();
-    const itemsGroup = screen.getByRole('group', { name: COPY.choicesFor(COPY.itemsSelector) });
-    expect(itemsChip()).toHaveClass('refine-chip');
-    expect(itemsChip()).toHaveAttribute('aria-pressed', 'false');
-    expect(within(itemsGroup).queryByText(COPY.enhanceItems)).not.toBeInTheDocument();
-    expect(screen.getByRole('button', { name: COPY.saveAndGenerate }).closest('.ui-actions')).not.toBeNull();
-  });
-
-  it('does not overwrite a typed items selector with candidates', async () => {
-    echoValidate();
-    const pendingSuggestion = Promise.withResolvers<Response>();
-    server.use(http.post('/api/v1/feeds/suggest_selectors', () => pendingSuggestion.promise));
-    renderStudio();
-    fireEvent.input(screen.getByLabelText(COPY.itemsSelector), { target: { value: 'article.mine' } });
-    pendingSuggestion.resolve(HttpResponse.json(suggestEnvelope('.post', true)));
-
-    await waitFor(() => expect(screen.getByText('.post')).toBeInTheDocument());
-    expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('article.mine');
-    expect(screen.getByLabelText(COPY.enhanceItems)).not.toBeChecked();
-  });
-
-  it('adds and removes selector parts from chips without changing enhance', async () => {
+  it('toggles one items chip without changing enhance', async () => {
     echoValidate();
     stubSuggest(
       rankedSuggestSuccessBody({
-        items: [
-          { selector: 'article, div', enhance: true },
-          { selector: 'main', enhance: false },
-        ],
-        title: [{ selector: 'h2' }],
+        items: [{ selector: 'article', enhance: true }],
       })
     );
     renderStudio();
-    await waitFor(() => expect(itemsChip(COPY.addSelector('article'))).toBeInTheDocument());
+    await waitForItemsChip();
 
-    fireEvent.input(screen.getByLabelText(COPY.itemsSelector), { target: { value: 'a[href]' } });
     fireEvent.click(screen.getByLabelText(COPY.enhanceItems));
     expect(screen.getByLabelText(COPY.enhanceItems)).toBeChecked();
 
-    const itemsGroup = screen.getByRole('group', { name: COPY.choicesFor(COPY.itemsSelector) });
-    fireEvent.click(within(itemsGroup).getByRole('button', { name: COPY.addSelector('article') }));
-    fireEvent.click(within(itemsGroup).getByRole('button', { name: COPY.addSelector('div') }));
-    fireEvent.click(within(itemsGroup).getByRole('button', { name: COPY.addSelector('main') }));
-
-    expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('a[href], article, div, main');
+    fireEvent.click(itemsChip(COPY.addSelector('article')));
+    expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('a[href], article');
     expect(screen.getByLabelText(COPY.enhanceItems)).toBeChecked();
-    expect(within(itemsGroup).getByRole('button', { name: COPY.removeSelector('article') })).toHaveAttribute(
-      'aria-pressed',
-      'true'
-    );
-    expect(within(itemsGroup).queryByText(COPY.enhanceItems)).not.toBeInTheDocument();
-
-    fireEvent.click(within(itemsGroup).getByRole('button', { name: COPY.removeSelector('article') }));
-
-    expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('a[href], div, main');
-    expect(screen.getByLabelText(COPY.enhanceItems)).toBeChecked();
-    expect(within(itemsGroup).getByRole('button', { name: COPY.addSelector('article') })).toHaveAttribute(
-      'aria-pressed',
-      'false'
-    );
-    expect(within(itemsGroup).getByRole('button', { name: COPY.removeSelector('div') })).toHaveAttribute(
-      'aria-pressed',
-      'true'
-    );
-    fireEvent.input(screen.getByLabelText(COPY.itemsSelector), { target: { value: 'a[href], main' } });
-    expect(within(itemsGroup).getByRole('button', { name: COPY.addSelector('div') })).toHaveAttribute(
-      'aria-pressed',
-      'false'
-    );
-    expect(within(itemsGroup).getByRole('button', { name: COPY.removeSelector('main') })).toHaveAttribute(
-      'aria-pressed',
-      'true'
-    );
-    expect(screen.getByRole('group', { name: COPY.choicesFor(COPY.fieldTitle) })).toBeInTheDocument();
-  });
+    expect(itemsChip(COPY.removeSelector('article'))).toHaveAttribute('aria-pressed', 'true');
 
-  it('adds a title chip without changing items or enhance', async () => {
-    echoValidate();
-    stubSuggest(
-      rankedSuggestSuccessBody({
-        items: [{ selector: 'article', enhance: true }],
-        title: [{ selector: 'h2' }, { selector: 'h1' }],
-      })
-    );
-    renderStudio();
-    await waitFor(() => expect(screen.getByText('h2')).toBeInTheDocument());
-    fireEvent.click(screen.getByLabelText(COPY.enhanceItems));
-
-    const titleGroup = screen.getByRole('group', { name: COPY.choicesFor(COPY.fieldTitle) });
-    fireEvent.click(within(titleGroup).getByRole('button', { name: COPY.addSelector('h2') }));
-
-    fireEvent.click(screen.getByRole('button', { name: COPY.fieldMissing(COPY.fieldTitle) }));
-    expect(screen.getByLabelText(COPY.selector)).toHaveValue('h2');
+    fireEvent.click(itemsChip(COPY.removeSelector('article')));
     expect(screen.getByLabelText(COPY.itemsSelector)).toHaveValue('a[href]');
     expect(screen.getByLabelText(COPY.enhanceItems)).toBeChecked();
-    expect(within(titleGroup).getByRole('button', { name: COPY.removeSelector('h2') })).toHaveAttribute(
-      'aria-pressed',
-      'true'
-    );
-    expect(within(titleGroup).getByRole('button', { name: COPY.addSelector('h1') })).toHaveAttribute(
-      'aria-pressed',
-      'false'
-    );
   });
 
   it('hides empty candidate buckets', async () => {
@@ -305,10 +156,6 @@ describe('ConfigStudio', () => {
     await waitFor(() => expect(screen.getByText('article')).toBeInTheDocument());
     expect(screen.getByRole('group', { name: COPY.selectorChoices })).toBeInTheDocument();
     expect(screen.queryByRole('group', { name: COPY.choicesFor(COPY.fieldTitle) })).not.toBeInTheDocument();
-    expect(screen.queryByRole('group', { name: COPY.choicesFor(COPY.fieldLink) })).not.toBeInTheDocument();
-    expect(
-      screen.queryByRole('group', { name: COPY.choicesFor(COPY.fieldPublished) })
-    ).not.toBeInTheDocument();
   });
 
   it('hides the choices region when every bucket is empty', async () => {
@@ -323,10 +170,10 @@ describe('ConfigStudio', () => {
   it('opens a fix-a-field selector panel without cleanup controls', async () => {
     server.use(
       http.post('/api/v1/feeds/validate', () =>
-        HttpResponse.json(
-          validateEnvelope(
-            { items: { selector: 'article', enhance: false } },
-            {
+        HttpResponse.json({
+          success: true,
+          data: {
+            report: {
               success: false,
               issues: [
                 {
@@ -340,9 +187,11 @@ describe('ConfigStudio', () => {
                   message: 'is invalid',
                 },
               ],
-            }
-          )
-        )
+            },
+            selectors: { items: { selector: 'article', enhance: false } },
+            yaml: 'selectors: {}',
+          },
+        })
       )
     );
 
@@ -359,48 +208,6 @@ describe('ConfigStudio', () => {
     expect(screen.getByRole('button', { name: COPY.issueCount(1) })).toBeInTheDocument();
   });
 
-  it('auto-fetches a preview with url and date after validation', async () => {
-    echoValidate();
-    stubPreview(
-      previewEnvelope(
-        [
-          {
-            title: 'Sample headline',
-            url: 'https://example.com/sample',
-            published_at: '2024-01-02',
-          },
-        ],
-        {
-          warnings: ['native_feed_present'],
-          metrics: { short_title_count: 0 },
-          native_feed: 'https://example.com/feed.xml',
-        }
-      )
-    );
-
-    renderStudio();
-
-    expect(screen.queryByRole('button', { name: COPY.previewChecking })).not.toBeInTheDocument();
-    fireEvent.click(await waitForItemsChip());
-    await waitFor(() => expect(screen.getByText('Sample headline')).toBeInTheDocument());
-    expect(screen.getByRole('link', { name: 'Sample headline' })).toHaveAttribute(
-      'href',
-      'https://example.com/sample'
-    );
-    expect(screen.getByText('https://example.com/sample')).toBeInTheDocument();
-    expect(screen.getByText('2024-01-02')).toBeInTheDocument();
-    expect(screen.getByRole('button', { name: COPY.fieldFound(COPY.fieldTitle) })).toBeInTheDocument();
-    expect(screen.getByRole('button', { name: COPY.fieldFound(COPY.fieldLink) })).toBeInTheDocument();
-    expect(screen.getByRole('button', { name: COPY.fieldFound(COPY.fieldPublished) })).toBeInTheDocument();
-    expect(screen.getByText(COPY.nativeFeedTitle)).toBeInTheDocument();
-    expect(screen.getByRole('link', { name: 'https://example.com/feed.xml' })).toHaveAttribute(
-      'href',
-      'https://example.com/feed.xml'
-    );
-    expect(screen.queryByText('native_feed_present')).not.toBeInTheDocument();
-    expect(document.querySelector('img.refine-sample-image')).toBeNull();
-  });
-
   it('renders a sample image only for an authenticated session when a url exists', async () => {
     echoValidate();
     stubPreview(previewWithImage());
@@ -410,14 +217,8 @@ describe('ConfigStudio', () => {
     await waitFor(() => expect(screen.getByText('With image')).toBeInTheDocument());
     const images = document.querySelectorAll('img.refine-sample-image');
     expect(images).toHaveLength(1);
-    const image = images[0];
-    expect(image).toBeInstanceOf(HTMLImageElement);
-    if (!(image instanceof HTMLImageElement)) return;
-    expect(image).toHaveAttribute('src', 'https://cdn.example/a.jpg');
-    expect(image).toHaveAttribute('referrerpolicy', 'no-referrer');
-    expect(image).toHaveAttribute('loading', 'lazy');
-    expect(image).not.toHaveAttribute('crossorigin');
-    expect(screen.getByText('No image')).toBeInTheDocument();
+    expect(images[0]).toHaveAttribute('src', 'https://cdn.example/a.jpg');
+    expect(images[0]).toHaveAttribute('referrerpolicy', 'no-referrer');
   });
 
   it('does not request a sample image without an access token', async () => {
@@ -430,49 +231,6 @@ describe('ConfigStudio', () => {
     expect(document.querySelector('img')).toBeNull();
   });
 
-  it('keeps the visible meadow while the next preview has not returned', async () => {
-    echoValidate();
-    const firstPreview = Promise.withResolvers<Response>();
-    let previewCalls = 0;
-    server.use(
-      http.post('/api/v1/feeds/preview', () => {
-        previewCalls += 1;
-        if (previewCalls === 1) return firstPreview.promise;
-        return HttpResponse.json(previewWithImage());
-      })
-    );
-
-    render(
-      <ConfigStudio
-        fallback={<p>Create-time meadow</p>}
-        url={pageUrl}
-        token="tok"
-        onGenerate={vi.fn(async () => {})}
-      />
-    );
-
-    expect(screen.getByText('Create-time meadow')).toBeInTheDocument();
-    fireEvent.click(await waitForItemsChip());
-
-    await waitFor(() => expect(screen.getByText(COPY.previewChecking)).toBeInTheDocument());
-    expect(screen.getByText('Create-time meadow')).toBeInTheDocument();
-    expect(screen.queryByText('With image')).not.toBeInTheDocument();
-
-    firstPreview.resolve(HttpResponse.json(previewWithImage()));
-    await waitFor(() => expect(screen.getByText('With image')).toBeInTheDocument());
-    expect(screen.queryByText('Create-time meadow')).not.toBeInTheDocument();
-    expect(screen.queryByText(COPY.previewChecking)).not.toBeInTheDocument();
-
-    const nextPreview = Promise.withResolvers<Response>();
-    server.use(http.post('/api/v1/feeds/preview', () => nextPreview.promise));
-    fireEvent.click(itemsChip(COPY.removeSelector('article')));
-
-    await waitFor(() => expect(screen.getByText(COPY.previewChecking)).toBeInTheDocument());
-    expect(screen.getByText('With image')).toBeInTheDocument();
-    expect(screen.queryByText('Create-time meadow')).not.toBeInTheDocument();
-    expect(document.querySelectorAll('.ui-item-list')).toHaveLength(1);
-  });
-
   it('offers check again when the live preview cannot be fetched', async () => {
     echoValidate();
     server.use(http.post('/api/v1/feeds/preview', () => HttpResponse.error()));
@@ -497,7 +255,6 @@ describe('ConfigStudio', () => {
     expect(screen.getByText(/url: https:\/\/example\.com\/articles/)).toBeInTheDocument();
     const yaml = document.querySelector('pre.refine-yaml');
     expect(yaml).toHaveClass('ui-card', 'ui-card--notice', 'input--mono');
-    expect(yaml).not.toHaveClass('input');
   });
 
   it('sends the validated selectors when generating a feed', async () => {
diff --git a/frontend/src/__tests__/selectorDraft.test.ts b/frontend/src/__tests__/selectorDraft.test.ts
index a59dc707..5feb6007 100644
--- a/frontend/src/__tests__/selectorDraft.test.ts
+++ b/frontend/src/__tests__/selectorDraft.test.ts
@@ -1,13 +1,21 @@
 import { describe, expect, it } from 'vitest';
 import {
+  draftFromSelectors,
+  emptyDraft,
   joinSelectorParts,
   selectorChoiceParts,
   hasEverySelectorPart,
+  selectorsFromDraft,
   splitSelectorParts,
   toggleSelectorParts,
+  withFieldSelector,
 } from '../studio/selectorDraft';
 
-describe('selector parts', () => {
+describe('selectorDraft', () => {
+  it('starts the items selector at the gem default a[href]', () => {
+    expect(emptyDraft().itemsSelector).toBe('a[href]');
+  });
+
   it('splits on commas outside parens, brackets, and quotes, and drops empty parts', () => {
     expect(splitSelectorParts('a[href], article, div')).toEqual(['a[href]', 'article', 'div']);
     expect(splitSelectorParts('article,,  div')).toEqual(['article', 'div']);
@@ -48,4 +56,47 @@ describe('selector parts', () => {
       selectorChoiceParts([{ selector: 'article, div' }, { selector: 'main' }, { selector: 'div, article' }])
     ).toEqual(['article', 'div', 'main']);
   });
+
+  it('round-trips closed field selectors without fixup or preserve bags', () => {
+    const drafted = draftFromSelectors({
+      items: { selector: 'article', enhance: true, order: 'reverse' },
+      guid: ['title'],
+      title: { selector: 'h2', extractor: 'text' },
+    });
+    expect(drafted).toBeDefined();
+    if (!drafted) return;
+
+    expect(drafted.itemsSelector).toBe('article');
+    expect(drafted.enhance).toBe(true);
+    expect(drafted.fields.title.selector).toBe('h2');
+
+    const withLink = withFieldSelector(drafted, 'link', 'a');
+    const withDate = withFieldSelector(withLink, 'published', 'time');
+    const wire = selectorsFromDraft(withDate);
+    expect(wire).toEqual({
+      items: { selector: 'article', enhance: true },
+      title: { selector: 'h2', extractor: 'text' },
+      url: { selector: 'a', extractor: 'href' },
+      published_at: { selector: 'time', extractor: 'text' },
+    });
+
+    const again = draftFromSelectors(wire);
+    expect(again?.fields.title.selector).toBe('h2');
+    expect(again?.fields.link.selector).toBe('a');
+    expect(again?.fields.published.selector).toBe('time');
+    expect(selectorsFromDraft(again ?? withDate)).toEqual(wire);
+  });
+
+  it('rejects field documents that still carry post_process', () => {
+    expect(
+      draftFromSelectors({
+        items: { selector: 'article' },
+        title: {
+          selector: 'h2',
+          extractor: 'text',
+          post_process: [{ name: 'gsub', pattern: 'x', replacement: '' }],
+        },
+      })
+    ).toBeUndefined();
+  });
 });
diff --git a/frontend/src/__tests__/useStudio.test.ts b/frontend/src/__tests__/useStudio.test.ts
index 5302944d..684b2460 100644
--- a/frontend/src/__tests__/useStudio.test.ts
+++ b/frontend/src/__tests__/useStudio.test.ts
@@ -1,113 +1,23 @@
-import { describe, it, expect, beforeEach, afterEach, vi, type SpyInstance } from 'vitest';
+import { describe, it, expect, afterEach, vi } from 'vitest';
 import { renderHook, act, waitFor } from '@testing-library/preact';
+import { http, HttpResponse } from 'msw';
+import { server } from './mocks/server';
 import {
-  draftFromSelectors,
-  emptyDraft,
-  selectorChoiceParts,
-  selectorsFromDraft,
-  withFieldSelector,
-} from '../studio/selectorDraft';
+  buildStructuredErrorResponse,
+  studioPreviewSuccessBody,
+  suggestSuccessBody,
+  validateSuccessBody,
+  validateYamlForSelectors,
+} from './mocks/apiFixtures';
 import {
   STUDIO_PREVIEW_SETTLE_MS,
   STUDIO_VALIDATE_DELAY_MS,
   canSaveStudio,
   useStudio,
 } from '../studio/useStudio';
-import { httpRequestUrl } from '../api/http/client';
 
 const pageUrl = 'https://example.com/articles';
 const token = 'studio-token';
-const wireNull: unknown = JSON.parse('null');
-
-function fetchPath(input: RequestInfo | URL): string {
-  return httpRequestUrl(input).pathname;
-}
-
-async function fetchJsonBody(input: RequestInfo | URL, init?: RequestInit): Promise<unknown> {
-  if (input instanceof Request) {
-    const text = await input.clone().text();
-    return text.trim() ? JSON.parse(text) : undefined;
-  }
-  return typeof init?.body === 'string' && init.body.trim() ? JSON.parse(init.body) : undefined;
-}
-
-function selectorsFromBody(parsed: unknown): unknown {
-  return typeof parsed === 'object' && parsed && 'selectors' in parsed ? parsed.selectors : undefined;
-}
-
-function validateBody(overrides: Record<string, unknown> = {}) {
-  return {
-    success: true,
-    data: {
-      report: { success: true, issues: [] },
-      selectors: { items: { selector: 'article', enhance: false } },
-      yaml: 'selectors:\n  items:\n    selector: article\n',
-      ...overrides,
-    },
-  };
-}
-
-function suggestionBody(isEnhanced = false, selector = 'article') {
-  return {
-    success: true,
-    data: {
-      candidates: {
-        items: [{ selector, enhance: isEnhanced }],
-        title: [],
-        link: [],
-        published: [],
-      },
-      segment_strategy: 'list',
-      admission_drops: { chrome: 2 },
-    },
-  };
-}
-
-function rankedSuggestionBody(buckets: {
-  items?: Array<{ selector: string; enhance?: boolean }>;
-  title?: Array<{ selector: string }>;
-  link?: Array<{ selector: string }>;
-  published?: Array<{ selector: string }>;
-}) {
-  return {
-    success: true,
-    data: {
-      candidates: {
-        items: (buckets.items ?? []).map((entry) => ({
-          selector: entry.selector,
-          enhance: entry.enhance === true,
-        })),
-        title: buckets.title ?? [],
-        link: buckets.link ?? [],
-        published: buckets.published ?? [],
-      },
-      segment_strategy: 'list',
-      admission_drops: { chrome: 0 },
-    },
-  };
-}
-
-function previewBody(sampleItems: unknown[], extras: Record<string, unknown> = {}) {
-  return {
-    success: true,
-    data: {
-      item_count: sampleItems.length,
-      sample_items: sampleItems,
-      quality_report: { warnings: [], metrics: { short_title_count: 0 } },
-      failure_kind: wireNull,
-      validation_issues: [],
-      ...extras,
-    },
-  };
-}
-
-function callsTo(fetchMock: SpyInstance, suffix: string) {
-  return fetchMock.mock.calls.filter((call) => {
-    const input = call[0];
-    if (input === undefined) return false;
-    return fetchPath(input).endsWith(suffix);
-  });
-}
 
 async function advanceValidate(ms = STUDIO_VALIDATE_DELAY_MS) {
   await act(async () => {
@@ -121,212 +31,79 @@ async function advancePreview(ms = STUDIO_PREVIEW_SETTLE_MS) {
   });
 }
 
-function mockStudioFetch(
-  fetchMock: SpyInstance,
-  handlers: {
-    suggest?: () => Promise<Response> | Response;
-    preview?: () => Promise<Response> | Response;
-    validate?: (selectors: unknown) => Promise<Response> | Response;
-  } = {}
-) {
-  fetchMock.mockImplementation(async (input: RequestInfo | URL, init?: RequestInit) => {
-    const path = fetchPath(input);
-    if (path.endsWith('/feeds/suggest_selectors')) {
-      return handlers.suggest?.() ?? Response.json(suggestionBody(false));
-    }
-    if (path.endsWith('/feeds/preview')) {
-      return handlers.preview?.() ?? Response.json(previewBody([]));
-    }
-    const parsed = await fetchJsonBody(input, init);
-    const selectors = selectorsFromBody(parsed);
-    if (handlers.validate) return handlers.validate(selectors);
-    return Response.json(
-      validateBody({
-        selectors: selectors ?? { items: { selector: 'article', enhance: false } },
-      })
-    );
-  });
-}
-
-describe('selector draft', () => {
-  it('starts the items selector at the gem default a[href]', () => {
-    expect(emptyDraft().itemsSelector).toBe('a[href]');
-  });
-
-  it('round-trips closed field selectors without fixup or preserve bags', () => {
-    const drafted = draftFromSelectors({
-      items: { selector: 'article', enhance: true, order: 'reverse' },
-      guid: ['title'],
-      title: { selector: 'h2', extractor: 'text' },
-    });
-    expect(drafted).toBeDefined();
-    if (!drafted) return;
-
-    expect(drafted.itemsSelector).toBe('article');
-    expect(drafted.enhance).toBe(true);
-    expect(drafted.fields.title.selector).toBe('h2');
-
-    const withLink = withFieldSelector(drafted, 'link', 'a');
-    const withDate = withFieldSelector(withLink, 'published', 'time');
-    const wire = selectorsFromDraft(withDate);
-    expect(wire).toEqual({
-      items: { selector: 'article', enhance: true },
-      title: { selector: 'h2', extractor: 'text' },
-      url: { selector: 'a', extractor: 'href' },
-      published_at: { selector: 'time', extractor: 'text' },
-    });
-
-    const again = draftFromSelectors(wire);
-    expect(again?.fields.title.selector).toBe('h2');
-    expect(again?.fields.link.selector).toBe('a');
-    expect(again?.fields.published.selector).toBe('time');
-    expect(selectorsFromDraft(again ?? withDate)).toEqual(wire);
-  });
-
-  it('rejects field documents that still carry post_process', () => {
-    expect(
-      draftFromSelectors({
-        items: { selector: 'article' },
-        title: {
-          selector: 'h2',
-          extractor: 'text',
-          post_process: [{ name: 'gsub', pattern: 'x', replacement: '' }],
-        },
-      })
-    ).toBeUndefined();
-  });
-
-  it('splits a multi-part candidate into parts the draft can add or remove independently', () => {
-    const drafted = draftFromSelectors({
-      items: { selector: 'a[href]', enhance: true },
-      title: { selector: '', extractor: 'text' },
-    });
-    expect(drafted).toBeDefined();
-    if (!drafted) return;
+function useStudioHandlers() {
+  let validateCount = 0;
+  let previewCount = 0;
+  let lastValidateAuth: string | null = null;
+
+  server.use(
+    http.post('/api/v1/feeds/suggest_selectors', () => HttpResponse.json(suggestSuccessBody('article', false))),
+    http.post('/api/v1/feeds/validate', async ({ request }) => {
+      validateCount += 1;
+      lastValidateAuth = request.headers.get('authorization');
+      const body = (await request.json()) as { selectors?: unknown; url?: string };
+      const selectors = body.selectors ?? { items: { selector: 'a[href]' } };
+      return HttpResponse.json(
+        validateSuccessBody(selectors, validateYamlForSelectors(selectors, body.url))
+      );
+    }),
+    http.post('/api/v1/feeds/preview', () => {
+      previewCount += 1;
+      return HttpResponse.json(
+        studioPreviewSuccessBody([
+          {
+            title: 'Sample',
+            url: 'https://example.com/sample',
+            published_at: '2024-01-02',
+          },
+        ])
+      );
+    })
+  );
 
-    expect(selectorChoiceParts([{ selector: 'article, div', enhance: true }, { selector: 'main' }])).toEqual([
-      'article',
-      'div',
-      'main',
-    ]);
-    expect(drafted.enhance).toBe(true);
-  });
-});
+  return {
+    validateCount: () => validateCount,
+    previewCount: () => previewCount,
+    lastValidateAuth: () => lastValidateAuth,
+  };
+}
 
 describe('useStudio', () => {
-  let fetchMock: SpyInstance;
-
-  beforeEach(() => {
-    vi.clearAllMocks();
-    fetchMock = vi.spyOn(globalThis, 'fetch');
-  });
-
   afterEach(() => {
-    fetchMock.mockRestore();
     vi.useRealTimers();
   });
 
-  it('waits 300ms, sends the bearer token, and unwraps a valid report', async () => {
+  it('waits for the validate delay, sends the bearer token, and unwraps a valid report', async () => {
     vi.useFakeTimers();
-    mockStudioFetch(fetchMock);
+    const handlers = useStudioHandlers();
 
     const { result } = renderHook(() => useStudio({ url: pageUrl, token }));
-    expect(callsTo(fetchMock, '/feeds/validate')).toHaveLength(0);
+    expect(handlers.validateCount()).toBe(0);
     expect(result.current.state.draft.itemsSelector).toBe('a[href]');
 
     await act(async () => {
       await vi.advanceTimersByTimeAsync(0);
       await Promise.resolve();
     });
-    expect(callsTo(fetchMock, '/feeds/validate')).toHaveLength(0);
-    expect(result.current.suggestion.items[0]?.selector).toBe('article');
-    expect(result.current.state.draft.itemsSelector).toBe('a[href]');
+    expect(handlers.validateCount()).toBe(0);
 
     await advanceValidate(STUDIO_VALIDATE_DELAY_MS - 1);
-    expect(callsTo(fetchMock, '/feeds/validate')).toHaveLength(0);
+    expect(handlers.validateCount()).toBe(0);
 
     await advanceValidate(1);
-
-    const validateCalls = callsTo(fetchMock, '/feeds/validate');
-    expect(validateCalls).toHaveLength(1);
-    const validateInput = validateCalls[0]?.[0];
-    expect(validateInput).toBeInstanceOf(Request);
-    if (!(validateInput instanceof Request)) return;
-    expect(fetchPath(validateInput)).toBe('/api/v1/feeds/validate');
-    expect(validateInput.headers.get('Authorization')).toBe(`Bearer ${token}`);
-    expect(JSON.parse(await validateInput.clone().text())).toEqual({
-      url: pageUrl,
-      selectors: { items: { selector: 'a[href]' } },
-    });
+    expect(handlers.validateCount()).toBe(1);
+    expect(handlers.lastValidateAuth()).toBe(`Bearer ${token}`);
 
     const state = result.current.state;
     expect(state.phase).toBe('editing');
     if (state.phase !== 'editing') return;
     expect(state.validated).toBe(true);
-    expect(state.yaml).toContain('article');
-    expect(state.draft.itemsSelector).toBe('a[href]');
-    expect(callsTo(fetchMock, '/feeds/preview')).toHaveLength(0);
-  });
-
-  it('keeps returned issue codes on the invalid phase and does not preview', async () => {
-    vi.useFakeTimers();
-    mockStudioFetch(fetchMock, {
-      validate: () =>
-        Response.json(
-          validateBody({
-            report: {
-              success: false,
-              issues: [
-                {
-                  path: ['selectors', 'items', 'selector'],
-                  code: 'missing_key',
-                  message: 'is missing',
-                },
-              ],
-            },
-            selectors: { items: { enhance: false } },
-            yaml: wireNull,
-          })
-        ),
-    });
-
-    const { result } = renderHook(() => useStudio({ url: pageUrl, token, validateDelayMs: 0 }));
-    await act(async () => {
-      await vi.advanceTimersByTimeAsync(0);
-    });
-    await act(async () => {
-      await Promise.resolve();
-    });
-    expect(result.current.state.phase).toBe('invalid');
-
-    const state = result.current.state;
-    if (state.phase !== 'invalid') return;
-    expect(state.issues).toEqual([
-      {
-        path: ['selectors', 'items', 'selector'],
-        code: 'missing_key',
-        message: 'is missing',
-      },
-    ]);
-
-    await advancePreview();
-    expect(callsTo(fetchMock, '/feeds/preview')).toHaveLength(0);
+    expect(handlers.previewCount()).toBe(0);
   });
 
   it('previews only after validation succeeds and the settle delay', async () => {
     vi.useFakeTimers();
-    mockStudioFetch(fetchMock, {
-      preview: () =>
-        Response.json(
-          previewBody([{ title: 'Sample', url: 'https://example.com/sample', published_at: '2024-01-02' }], {
-            quality_report: {
-              warnings: [],
-              metrics: { short_title_count: 0 },
-              native_feed: 'https://example.com/feed.xml',
-            },
-          })
-        ),
-    });
+    const handlers = useStudioHandlers();
 
     const { result } = renderHook(() =>
       useStudio({ url: pageUrl, token, validateDelayMs: STUDIO_VALIDATE_DELAY_MS })
@@ -335,342 +112,29 @@ describe('useStudio', () => {
     await act(async () => {
       await vi.advanceTimersByTimeAsync(0);
     });
-    expect(result.current.state.draft.itemsSelector).toBe('a[href]');
 
     await advanceValidate();
     await advancePreview();
-    expect(callsTo(fetchMock, '/feeds/preview')).toHaveLength(0);
+    expect(handlers.previewCount()).toBe(0);
     expect(result.current.state.live.status).toBe('idle');
 
     act(() => {
       result.current.setItemsSelector('article.edited');
     });
     await advanceValidate();
-    expect(callsTo(fetchMock, '/feeds/preview')).toHaveLength(0);
+    expect(handlers.previewCount()).toBe(0);
 
     await advancePreview(STUDIO_PREVIEW_SETTLE_MS - 1);
-    expect(callsTo(fetchMock, '/feeds/preview')).toHaveLength(0);
+    expect(handlers.previewCount()).toBe(0);
 
     await advancePreview(1);
-
-    const state = result.current.state;
-    expect(state.live.status).toBe('ready');
-    if (state.live.status !== 'ready') return;
-    expect(state.live.sample).toEqual({
-      itemCount: 1,
-      items: [
-        {
-          title: 'Sample',
-          url: 'https://example.com/sample',
-          publishedAt: '2024-01-02',
-          imageUrl: undefined,
-        },
-      ],
-      nativeFeedUrl: 'https://example.com/feed.xml',
-      failureKind: undefined,
-    });
-    expect(callsTo(fetchMock, '/feeds/preview')).toHaveLength(1);
-  });
-
-  it('keeps the previous sample while the next preview has not returned', async () => {
-    const firstItem = {
-      title: 'Held meadow',
-      url: 'https://example.com/held',
-      published_at: '2024-01-02',
-    };
-    let previewCount = 0;
-    const pendingPreview = Promise.withResolvers<Response>();
-    mockStudioFetch(fetchMock, {
-      preview: () => {
-        previewCount += 1;
-        if (previewCount === 1) return Response.json(previewBody([firstItem]));
-        return pendingPreview.promise;
-      },
-    });
-
-    const { result } = renderHook(() =>
-      useStudio({ url: pageUrl, token, validateDelayMs: 0, previewSettleMs: 0 })
-    );
-
-    act(() => {
-      result.current.setItemsSelector('article.held');
-    });
-
-    await waitFor(() => expect(result.current.state.live.status).toBe('ready'));
-    const ready = result.current.state.live;
-    if (ready.status !== 'ready') return;
-    const previous = ready.sample;
-    expect(previous.items[0]?.title).toBe('Held meadow');
-
-    act(() => {
-      result.current.setItemsSelector('article.edited');
-    });
-
-    const refreshing = result.current.state.live;
-    expect(refreshing.status).toBe('loading');
-    if (refreshing.status !== 'loading') return;
-    expect(refreshing.held).toEqual(previous);
-
-    await waitFor(() => expect(callsTo(fetchMock, '/feeds/preview')).toHaveLength(2));
-    const inFlight = result.current.state.live;
-    expect(inFlight.status).toBe('loading');
-    if (inFlight.status !== 'loading') return;
-    expect(inFlight.held).toEqual(previous);
-
-    pendingPreview.resolve(
-      Response.json(previewBody([{ title: 'Next meadow', url: 'https://example.com/next' }]))
-    );
-    await waitFor(() => expect(result.current.state.live.status).toBe('ready'));
-    const next = result.current.state.live;
-    if (next.status !== 'ready') return;
-    expect(next.sample.items[0]?.title).toBe('Next meadow');
-  });
-
-  it('suggests on mount without preview when live work waits for an edit', async () => {
-    mockStudioFetch(fetchMock);
-
-    const { result } = renderHook(() =>
-      useStudio({ url: pageUrl, token, validateDelayMs: 0, previewSettleMs: 0 })
-    );
-
-    await waitFor(() => {
-      expect(callsTo(fetchMock, '/feeds/validate').length).toBeGreaterThan(0);
-    });
-    await waitFor(() => expect(result.current.suggestion.items[0]?.selector).toBe('article'));
-    expect(callsTo(fetchMock, '/feeds/preview')).toHaveLength(0);
-    expect(result.current.state.live.status).toBe('idle');
-    expect(result.current.state.draft.itemsSelector).toBe('a[href]');
-
-    act(() => {
-      result.current.setItemsSelector('article.edited');
-    });
-
-    await waitFor(() => {
-      expect(callsTo(fetchMock, '/feeds/preview')).toHaveLength(1);
-    });
+    expect(handlers.previewCount()).toBe(1);
     expect(result.current.state.live.status).toBe('ready');
   });
 
-  it('stores ranked candidates without overwriting the draft until a chip is toggled', async () => {
-    const pendingSuggestion = Promise.withResolvers<Response>();
-    mockStudioFetch(fetchMock, {
-      suggest: () => pendingSuggestion.promise,
-      validate: (selectors) =>
-        Response.json(
-          validateBody({
-            selectors: selectors ?? { items: { selector: 'a[href]', enhance: false } },
-            yaml: 'selectors: {}\n',
-          })
-        ),
-    });
-
-    const { result } = renderHook(() =>
-      useStudio({ url: pageUrl, token, validateDelayMs: 0, previewSettleMs: 60_000 })
-    );
-
-    expect(result.current.state.draft.itemsSelector).toBe('a[href]');
-    expect(result.current.suggestion.items).toEqual([]);
-
-    await waitFor(() => expect(callsTo(fetchMock, '/feeds/suggest_selectors')).toHaveLength(1));
-    const suggestInput = callsTo(fetchMock, '/feeds/suggest_selectors')[0]?.[0];
-    expect(suggestInput).toBeInstanceOf(Request);
-    if (!(suggestInput instanceof Request)) return;
-    expect(JSON.parse(await suggestInput.clone().text())).toEqual({
-      url: pageUrl,
-    });
-
-    await act(async () => {
-      pendingSuggestion.resolve(
-        Response.json(
-          rankedSuggestionBody({
-            items: [
-              { selector: '.post', enhance: true },
-              { selector: 'article', enhance: false },
-            ],
-            title: [{ selector: 'h2' }],
-            link: [{ selector: 'a' }],
-            published: [{ selector: 'time' }],
-          })
-        )
-      );
-    });
-
-    await waitFor(() => expect(result.current.suggestion.items[0]?.selector).toBe('.post'));
-    expect(result.current.suggestion.items).toEqual([
-      { selector: '.post', enhance: true },
-      { selector: 'article', enhance: false },
-    ]);
-    expect(result.current.suggestion.title).toEqual([{ selector: 'h2' }]);
-    expect(result.current.suggestion.link).toEqual([{ selector: 'a' }]);
-    expect(result.current.suggestion.published).toEqual([{ selector: 'time' }]);
-    expect(result.current.state.draft.itemsSelector).toBe('a[href]');
-    expect(result.current.state.draft.enhance).toBe(false);
-    expect(result.current.state.draft.fields.title.selector).toBe('');
-    expect(callsTo(fetchMock, '/feeds/suggest_selectors')).toHaveLength(1);
-
-    act(() => {
-      result.current.toggleItemsSelector('.post');
-    });
-
-    expect(result.current.state.draft.itemsSelector).toBe('a[href], .post');
-    expect(result.current.state.draft.enhance).toBe(false);
-    expect(result.current.state.draft.fields.title.selector).toBe('');
-  });
-
-  it('keeps a typed items selector while still exposing candidates', async () => {
-    const pendingSuggestion = Promise.withResolvers<Response>();
-    mockStudioFetch(fetchMock, {
-      suggest: () => pendingSuggestion.promise,
-      preview: () => Response.json(previewBody([], { quality_report: wireNull })),
-    });
-
-    const { result } = renderHook(() =>
-      useStudio({ url: pageUrl, token, validateDelayMs: 0, previewSettleMs: 60_000 })
-    );
-
-    act(() => {
-      result.current.setItemsSelector('article.mine');
-    });
-
-    await act(async () => {
-      pendingSuggestion.resolve(Response.json(suggestionBody(true, '.post')));
-    });
-
-    await waitFor(() => expect(result.current.suggestion.items[0]?.selector).toBe('.post'));
-    expect(result.current.state.draft.itemsSelector).toBe('article.mine');
-    expect(result.current.state.draft.enhance).toBe(false);
-    expect(callsTo(fetchMock, '/feeds/suggest_selectors')).toHaveLength(1);
-  });
-
-  it('keeps an http image url from the preview sample and drops anything else', async () => {
-    mockStudioFetch(fetchMock, {
-      preview: () =>
-        Response.json(
-          previewBody(
-            [
-              {
-                title: 'With image',
-                url: 'https://example.com/a',
-                published_at: '2024-01-02',
-                image: 'https://cdn.example/a.jpg',
-              },
-              { title: 'Unsafe image', image: 'javascript:alert(1)' },
-            ],
-            { quality_report: wireNull }
-          )
-        ),
-    });
-
-    const { result } = renderHook(() =>
-      useStudio({ url: pageUrl, token, validateDelayMs: 0, previewSettleMs: 0 })
-    );
-
-    act(() => {
-      result.current.setItemsSelector('article.imaged');
-    });
-
-    await waitFor(() => expect(result.current.state.live.status).toBe('ready'));
-    const live = result.current.state.live;
-    if (live.status !== 'ready') return;
-    expect(live.sample.items[0]?.imageUrl).toBe('https://cdn.example/a.jpg');
-    expect(live.sample.items[1]?.imageUrl).toBeUndefined();
-  });
-
-  it('toggles only the clicked items parts and leaves enhance unchanged', async () => {
-    mockStudioFetch(fetchMock, {
-      suggest: () =>
-        Response.json(
-          rankedSuggestionBody({
-            items: [
-              { selector: '.post', enhance: true },
-              { selector: 'article', enhance: false },
-            ],
-            title: [{ selector: 'h2' }],
-          })
-        ),
-      preview: () => Response.json(previewBody([], { quality_report: wireNull })),
-    });
-
-    const { result } = renderHook(() =>
-      useStudio({ url: pageUrl, token, validateDelayMs: 0, previewSettleMs: 60_000 })
-    );
-    await waitFor(() => expect(result.current.suggestion.items).toHaveLength(2));
-
-    act(() => {
-      result.current.setItemsSelector('article.bad');
-      result.current.setEnhance(false);
-    });
-    expect(result.current.state.draft.itemsSelector).toBe('article.bad');
-    expect(result.current.state.draft.enhance).toBe(false);
-
-    act(() => {
-      result.current.toggleItemsSelector('.post');
-    });
-
-    expect(result.current.state.draft.itemsSelector).toBe('article.bad, .post');
-    expect(result.current.state.draft.enhance).toBe(false);
-    expect(result.current.state.draft.fields.title.selector).toBe('');
-    expect(result.current.suggestion.title).toEqual([{ selector: 'h2' }]);
-
-    act(() => {
-      result.current.toggleItemsSelector('article, div');
-    });
-    act(() => {
-      result.current.toggleItemsSelector('article');
-    });
-
-    expect(result.current.state.draft.itemsSelector).toBe('article.bad, .post, div');
-    expect(result.current.state.draft.enhance).toBe(false);
-  });
-
-  it('toggles only the clicked field parts', async () => {
-    mockStudioFetch(fetchMock, {
-      suggest: () =>
-        Response.json(
-          rankedSuggestionBody({
-            items: [{ selector: 'article', enhance: false }],
-            title: [{ selector: 'h2' }, { selector: 'h1' }],
-          })
-        ),
-      preview: () => Response.json(previewBody([], { quality_report: wireNull })),
-    });
-
-    const { result } = renderHook(() =>
-      useStudio({ url: pageUrl, token, validateDelayMs: 0, previewSettleMs: 60_000 })
-    );
-    await waitFor(() => expect(result.current.suggestion.title).toHaveLength(2));
-
-    act(() => {
-      result.current.setEnhance(true);
-      result.current.toggleFieldSelector('title', 'h2');
-    });
-
-    expect(result.current.state.draft.fields.title.selector).toBe('h2');
-    expect(result.current.state.draft.itemsSelector).toBe('a[href]');
-    expect(result.current.state.draft.enhance).toBe(true);
-  });
-
-  it('returns to a save-enabled editing phase after generate', async () => {
-    vi.useFakeTimers();
-    mockStudioFetch(fetchMock);
-    const { result } = renderHook(() => useStudio({ url: pageUrl, token, validateDelayMs: 0 }));
-    await advanceValidate(0);
-    expect(canSaveStudio(result.current.state)).toBe(true);
-
-    await act(async () => {
-      await result.current.save(async () => {});
-    });
-
-    expect(result.current.state.phase).toBe('editing');
-    const state = result.current.state;
-    if (state.phase !== 'editing') return;
-    expect(state.validated).toBe(true);
-    expect(canSaveStudio(state)).toBe(true);
-  });
-
   it('ignores a stale save after a newer save starts', async () => {
     vi.useFakeTimers();
-    mockStudioFetch(fetchMock);
+    useStudioHandlers();
     const { result } = renderHook(() => useStudio({ url: pageUrl, token, validateDelayMs: 0 }));
     await advanceValidate(0);
 
@@ -703,20 +167,18 @@ describe('useStudio', () => {
   });
 
   it('fails closed when validate is unauthorized', async () => {
-    fetchMock.mockImplementation(() =>
-      Promise.resolve(
-        Response.json(
-          {
-            success: false,
-            error: {
-              code: 'UNAUTHORIZED',
-              message: 'Authentication required',
-              kind: 'auth',
-              retryable: false,
-              next_action: 'enter_token',
-              retry_action: 'none',
-            },
-          },
+    server.use(
+      http.post('/api/v1/feeds/suggest_selectors', () => HttpResponse.json(suggestSuccessBody())),
+      http.post('/api/v1/feeds/validate', () =>
+        HttpResponse.json(
+          buildStructuredErrorResponse({
+            code: 'UNAUTHORIZED',
+            message: 'Authentication required',
+            kind: 'auth',
+            retryable: false,
+            next_action: 'enter_token',
+            retry_action: 'none',
+          }),
           { status: 401 }
         )
       )

From afd54354c9578117b501ac9df689ee4d2ddda716 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Tue, 22 Sep 2026 00:06:04 +0200
Subject: [PATCH 103/108] test(frontend): split Node and jsdom projects

---
 Makefile                                      |   6 +-
 docs/README.md                                |  20 +-
 frontend/eslint.config.js                     |   1 -
 frontend/package.json                         |   4 +-
 ...ract.test.tsx => App.integration.test.tsx} |  18 +-
 .../src/__tests__/bookmarkletHref.test.ts     |  16 ++
 .../src/__tests__/feedWorkflowStorage.test.ts |   9 +-
 frontend/src/__tests__/mocks/apiFixtures.ts   |   2 +
 .../src/__tests__/persistentStorage.test.ts   |  42 +++++
 frontend/src/__tests__/setup.ts               | 102 +++--------
 frontend/src/__tests__/setup.unit.ts          |   5 +
 .../useFeedCreation.contract.test.ts          | 172 ------------------
 .../src/__tests__/useFeedCreation.test.ts     |  66 ++++++-
 frontend/src/__tests__/useStudio.test.ts      |  12 +-
 frontend/src/api/http/client.ts               |   3 +-
 frontend/src/components/Bookmarklet.tsx       |  13 +-
 frontend/src/routes/bookmarkletHref.ts        |  14 ++
 frontend/tsconfig.json                        |   2 +-
 frontend/vitest.config.js                     |  51 +++++-
 frontend/vitest.contract.config.ts            |   8 -
 frontend/vitest.unit.config.ts                |   8 -
 21 files changed, 248 insertions(+), 326 deletions(-)
 rename frontend/src/__tests__/{App.contract.test.tsx => App.integration.test.tsx} (97%)
 create mode 100644 frontend/src/__tests__/bookmarkletHref.test.ts
 create mode 100644 frontend/src/__tests__/persistentStorage.test.ts
 create mode 100644 frontend/src/__tests__/setup.unit.ts
 delete mode 100644 frontend/src/__tests__/useFeedCreation.contract.test.ts
 create mode 100644 frontend/src/routes/bookmarkletHref.ts
 delete mode 100644 frontend/vitest.contract.config.ts
 delete mode 100644 frontend/vitest.unit.config.ts

diff --git a/Makefile b/Makefile
index eb6cd2af..157cd9f6 100644
--- a/Makefile
+++ b/Makefile
@@ -54,11 +54,11 @@ test-ruby: ## Run Ruby tests only
 test-frontend: ## Run frontend tests only
 	@cd frontend && pnpm run test:ci
 
-test-frontend-unit: ## Run frontend unit tests only
+test-frontend-unit: ## Run frontend Node unit tests only
 	@cd frontend && pnpm run test:unit
 
-test-frontend-contract: ## Run frontend contract tests only
-	@cd frontend && pnpm run test:contract
+test-frontend-integration: ## Run frontend jsdom integration tests only
+	@cd frontend && pnpm run test:integration
 
 test-frontend-e2e: ## Run frontend Playwright smoke tests
 	@cd frontend && pnpm run test:e2e
diff --git a/docs/README.md b/docs/README.md
index a7e52e87..281f1c72 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -59,9 +59,9 @@ Running the app directly on the host is not supported.
 | `pnpm run dev`           | Vite dev server with hot reload (port 4001). |
 | `pnpm run build`         | Build static assets into `frontend/dist/`.   |
 | `pnpm run lint`          | Run ESLint across the frontend workspace.    |
-| `pnpm run test:run`      | All Vitest tests (unit + contract).          |
-| `pnpm run test:unit`     | Unit tests only (excludes `*.contract.test.*`). |
-| `pnpm run test:contract` | Contract tests with MSW.                     |
+| `pnpm run test:run`      | All Vitest projects (Node unit + jsdom integration). |
+| `pnpm run test:unit`     | Node project: parsers, routes, drafts, storage, apiHttp. |
+| `pnpm run test:integration` | jsdom project: App, ConfigStudio, ResultDisplay, timer hooks. |
 | `pnpm run test:e2e`      | Playwright smoke (one worker).               |
 
 Development routing defaults:
@@ -103,13 +103,13 @@ make ci-ready
 
 ### Testing Layers
 
-| Layer             | Tooling                  | Focus                                                |
-| ----------------- | ------------------------ | ---------------------------------------------------- |
-| Ruby API          | RSpec + Rack::Test       | Feed creation, retrieval, auth paths.                |
-| Frontend unit     | Vitest + Testing Library | Component rendering and hooks with mocked fetch.     |
-| Frontend contract | Vitest + MSW             | End-to-end fetch flows against mocked API responses. |
-| Frontend e2e      | Playwright               | Stubbed SPA smoke: create/token/result/refine journeys. |
-| Docker smoke      | RSpec (`:docker`)        | Net::HTTP probes against the containerised service.  |
+| Layer                  | Tooling                  | Focus                                                |
+| ---------------------- | ------------------------ | ---------------------------------------------------- |
+| Ruby API               | RSpec + Rack::Test       | Feed creation, retrieval, auth paths.                |
+| Frontend unit          | Vitest (Node)            | Parsers, routes, drafts, storage, apiHttp adapters.  |
+| Frontend integration   | Vitest (jsdom) + MSW     | App and ConfigStudio with real hooks; timer hooks.   |
+| Frontend e2e           | Playwright               | Stubbed SPA smoke: create/token/result/refine journeys. |
+| Docker smoke           | RSpec (`:docker`)        | Net::HTTP probes against the containerised service.  |
 
 ---
 
diff --git a/frontend/eslint.config.js b/frontend/eslint.config.js
index ceac7928..3796ffdb 100644
--- a/frontend/eslint.config.js
+++ b/frontend/eslint.config.js
@@ -21,7 +21,6 @@ export default tseslint.config(
       globals: {
         ...globals.browser,
         ...globals.node,
-        ...globals.vitest,
       },
     },
     plugins: {
diff --git a/frontend/package.json b/frontend/package.json
index 4a34ac8e..3e55d8e1 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -18,8 +18,8 @@
     "openapi:verify": "openapi-ts && git diff --exit-code -- src/api/generated",
     "test": "vitest",
     "test:run": "vitest run",
-    "test:unit": "vitest run --reporter=verbose --config vitest.unit.config.ts",
-    "test:contract": "vitest run --reporter=verbose --config vitest.contract.config.ts",
+    "test:unit": "vitest run --project unit --reporter=verbose",
+    "test:integration": "vitest run --project integration --reporter=verbose",
     "test:ci": "pnpm run test:run",
     "test:e2e": "playwright test"
   },
diff --git a/frontend/src/__tests__/App.contract.test.tsx b/frontend/src/__tests__/App.integration.test.tsx
similarity index 97%
rename from frontend/src/__tests__/App.contract.test.tsx
rename to frontend/src/__tests__/App.integration.test.tsx
index b3536e8f..775ed17b 100644
--- a/frontend/src/__tests__/App.contract.test.tsx
+++ b/frontend/src/__tests__/App.integration.test.tsx
@@ -123,9 +123,7 @@ describe('App', () => {
     localStorage.setItem('html2rss_access_token', ACCESS_TOKEN);
     const createCount = { value: 0 };
     useSuccessfulCreate(createCount);
-    server.use(
-      http.get('/api/v1/configs', () => HttpResponse.json(catalogBody([bbcMundo, bbcSounds])))
-    );
+    server.use(http.get('/api/v1/configs', () => HttpResponse.json(catalogBody([bbcMundo, bbcSounds]))));
 
     const user = await renderApp();
     const urlField = screen.getByLabelText(COPY.urlLabel);
@@ -142,12 +140,12 @@ describe('App', () => {
     const createCount = { value: 0 };
     useSuccessfulCreate(createCount);
 
-    const user = await renderApp();
+    await renderApp();
     const urlField = screen.getByLabelText(COPY.urlLabel);
-    await user.type(urlField, EXAMPLE_URL);
-    await user.keyboard('{Enter}');
-    urlField.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true, repeat: true }));
-    urlField.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true, repeat: true }));
+    fireEvent.input(urlField, { target: { value: EXAMPLE_URL } });
+    fireEvent.keyDown(urlField, { key: 'Enter' });
+    fireEvent.keyDown(urlField, { key: 'Enter', repeat: true });
+    fireEvent.keyDown(urlField, { key: 'Enter', repeat: true });
 
     await screen.findByText(COPY.feedReady);
     expect(createCount.value).toBe(1);
@@ -403,9 +401,7 @@ describe('App', () => {
     await waitFor(() => expect(bodies).toHaveLength(2));
     expect(bodies[1]).toMatchObject({ url: EXAMPLE_URL });
     expect(
-      bodies[1] && typeof bodies[1] === 'object' && 'selectors' in bodies[1]
-        ? bodies[1].selectors
-        : undefined
+      bodies[1] && typeof bodies[1] === 'object' && 'selectors' in bodies[1] ? bodies[1].selectors : undefined
     ).toEqual({ items: { selector: 'a[href], article' } });
     await screen.findByText(COPY.feedReady);
   });
diff --git a/frontend/src/__tests__/bookmarkletHref.test.ts b/frontend/src/__tests__/bookmarkletHref.test.ts
new file mode 100644
index 00000000..293692dc
--- /dev/null
+++ b/frontend/src/__tests__/bookmarkletHref.test.ts
@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'vitest';
+import { buildBookmarkletHref } from '../routes/bookmarkletHref';
+
+describe('buildBookmarkletHref', () => {
+  it('builds a javascript assign to the create route with encoded current href', () => {
+    const href = buildBookmarkletHref('http://localhost:3000/');
+    expect(href).toBe(
+      'javascript:window.location.assign("http://localhost:3000/#/create?url="+encodeURIComponent(window.location.href));'
+    );
+    expect(href).not.toContain('%27+encodeURIComponent');
+  });
+
+  it('returns a hash placeholder when window is unavailable and no base is given', () => {
+    expect(buildBookmarkletHref()).toBe('#');
+  });
+});
diff --git a/frontend/src/__tests__/feedWorkflowStorage.test.ts b/frontend/src/__tests__/feedWorkflowStorage.test.ts
index c4ca6af9..e310273f 100644
--- a/frontend/src/__tests__/feedWorkflowStorage.test.ts
+++ b/frontend/src/__tests__/feedWorkflowStorage.test.ts
@@ -1,10 +1,10 @@
 import { beforeEach, describe, expect, it } from 'vitest';
 import { clearFeedDraftState, loadFeedDraftState, saveFeedDraftState } from '../utils/feedWorkflowStorage';
+import { getPersistentStorage } from '../utils/persistentStorage';
 
 describe('feedWorkflowStorage', () => {
   beforeEach(() => {
-    localStorage.clear();
-    sessionStorage.clear();
+    getPersistentStorage().clear();
   });
 
   it('persists and hydrates the create draft state from the url only', () => {
@@ -13,16 +13,13 @@ describe('feedWorkflowStorage', () => {
     expect(loadFeedDraftState()).toEqual({
       url: 'https://example.com/articles',
     });
-    expect(localStorage.getItem('html2rss_feed_draft_state')).toBe(
-      JSON.stringify({ url: 'https://example.com/articles' })
-    );
 
     clearFeedDraftState();
     expect(loadFeedDraftState()).toBeUndefined();
   });
 
   it('ignores extra draft properties beyond the canonical shape', () => {
-    localStorage.setItem(
+    getPersistentStorage().setItem(
       'html2rss_feed_draft_state',
       JSON.stringify({
         url: 'https://example.com/articles',
diff --git a/frontend/src/__tests__/mocks/apiFixtures.ts b/frontend/src/__tests__/mocks/apiFixtures.ts
index 93cf51ea..044d9eca 100644
--- a/frontend/src/__tests__/mocks/apiFixtures.ts
+++ b/frontend/src/__tests__/mocks/apiFixtures.ts
@@ -248,6 +248,8 @@ export function studioPreviewSuccessBody(
       item_count: items.length,
       sample_items: items,
       quality_report: { warnings: [], metrics: { short_title_count: 0 } },
+      // OpenAPI `failure_kind` is `string | null`; fixtures use null for absence.
+      // eslint-disable-next-line unicorn/no-null -- wire absence is null, not undefined
       failure_kind: null,
       validation_issues: [],
     },
diff --git a/frontend/src/__tests__/persistentStorage.test.ts b/frontend/src/__tests__/persistentStorage.test.ts
new file mode 100644
index 00000000..18b97164
--- /dev/null
+++ b/frontend/src/__tests__/persistentStorage.test.ts
@@ -0,0 +1,42 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { getPersistentStorage } from '../utils/persistentStorage';
+
+describe('getPersistentStorage', () => {
+  afterEach(() => {
+    Reflect.deleteProperty(globalThis, 'window');
+    Reflect.deleteProperty(globalThis, 'localStorage');
+    Reflect.deleteProperty(globalThis, 'sessionStorage');
+  });
+
+  it('uses the in-memory store when window is unavailable', () => {
+    const storage = getPersistentStorage();
+    storage.clear();
+    storage.setItem('k', 'v');
+    expect(storage.getItem('k')).toBe('v');
+    storage.removeItem('k');
+    expect(storage.getItem('k')).toBeNull();
+  });
+
+  it('falls back to memory when localStorage and sessionStorage throw on access', () => {
+    Object.defineProperties(globalThis, {
+      window: { value: globalThis, configurable: true },
+      localStorage: {
+        configurable: true,
+        get() {
+          throw new Error('blocked');
+        },
+      },
+      sessionStorage: {
+        configurable: true,
+        get() {
+          throw new Error('blocked');
+        },
+      },
+    });
+
+    const storage = getPersistentStorage();
+    storage.clear();
+    storage.setItem('memory-key', 'memory-value');
+    expect(storage.getItem('memory-key')).toBe('memory-value');
+  });
+});
diff --git a/frontend/src/__tests__/setup.ts b/frontend/src/__tests__/setup.ts
index f7e7f3af..50014eb1 100644
--- a/frontend/src/__tests__/setup.ts
+++ b/frontend/src/__tests__/setup.ts
@@ -1,100 +1,40 @@
-import '@testing-library/jest-dom';
-import { afterAll, afterEach, beforeAll, beforeEach, vi } from 'vitest';
+import '@testing-library/jest-dom/vitest';
+import { afterAll, afterEach, beforeAll, vi } from 'vitest';
 import { cleanup } from '@testing-library/preact';
+import { server } from './mocks/server';
 
-let server: typeof import('./mocks/server').server;
-
-// Mock window and document for tests
 Object.defineProperty(globalThis, 'matchMedia', {
   writable: true,
-  value: vi.fn().mockImplementation((query) => ({
+  value: (query: string) => ({
     matches: false,
     media: query,
     onchange: undefined,
-    addListener: vi.fn(), // deprecated
-    removeListener: vi.fn(), // deprecated
-    addEventListener: vi.fn(),
-    removeEventListener: vi.fn(),
-    dispatchEvent: vi.fn(),
-  })),
-});
-
-// Persistent storage stubs with in-memory backing store
-const createStorageMock = () => {
-  const store = new Map<string, string>();
-
-  return {
-    store,
-    api: {
-      get length() {
-        return store.size;
-      },
-      // eslint-disable-next-line unicorn/no-null -- Web Storage returns null for missing keys.
-      getItem: vi.fn((key: string) => (store.has(key) ? store.get(key)! : null)),
-      setItem: vi.fn((key: string, value: string) => {
-        store.set(key, value);
-      }),
-      removeItem: vi.fn((key: string) => {
-        store.delete(key);
-      }),
-      clear: vi.fn(() => {
-        store.clear();
-      }),
-      // eslint-disable-next-line unicorn/no-null, unicorn/prefer-iterator-to-array -- Web Storage key() returns null for out-of-range indexes.
-      key: vi.fn((index: number) => [...store.keys()][index] ?? null),
-    },
-  };
-};
-
-const local = createStorageMock();
-const session = createStorageMock();
-
-Object.defineProperties(globalThis, {
-  localStorage: {
-    value: local.api,
-    configurable: true,
-    writable: true,
-  },
-  sessionStorage: {
-    value: session.api,
-    configurable: true,
-    writable: true,
-  },
+    addListener: () => {},
+    removeListener: () => {},
+    addEventListener: () => {},
+    removeEventListener: () => {},
+    dispatchEvent: () => false,
+  }),
 });
 
-beforeEach(() => {
-  local.store.clear();
-  session.store.clear();
-  local.api.getItem.mockClear();
-  local.api.setItem.mockClear();
-  local.api.removeItem.mockClear();
-  local.api.clear.mockClear();
-  local.api.key.mockClear();
-  session.api.getItem.mockClear();
-  session.api.setItem.mockClear();
-  session.api.removeItem.mockClear();
-  session.api.clear.mockClear();
-  session.api.key.mockClear();
+const clipboardWriteText = vi.fn(() => Promise.resolve());
+Object.defineProperty(navigator, 'clipboard', {
+  configurable: true,
+  value: { writeText: clipboardWriteText },
 });
 
-// Mock clipboard API
-Object.assign(navigator, {
-  clipboard: {
-    writeText: vi.fn(() => Promise.resolve()),
-  },
-});
-
-// Ensure scrollIntoView exists for components relying on it
 Element.prototype.scrollIntoView = vi.fn();
 
-// Wire up MSW in node environment
-beforeAll(async () => {
-  // eslint-disable-next-line unicorn/no-top-level-assignment-in-function
-  ({ server } = await import('./mocks/server'));
+beforeAll(() => {
   server.listen({ onUnhandledRequest: 'error' });
 });
+
 afterEach(() => {
   server.resetHandlers();
   cleanup();
+  clipboardWriteText.mockClear();
+});
+
+afterAll(() => {
+  server.close();
 });
-afterAll(() => server.close());
diff --git a/frontend/src/__tests__/setup.unit.ts b/frontend/src/__tests__/setup.unit.ts
new file mode 100644
index 00000000..9c9e0a39
--- /dev/null
+++ b/frontend/src/__tests__/setup.unit.ts
@@ -0,0 +1,5 @@
+/** Minimal DOM location for Node unit tests that exercise same-origin HTTP adapters. */
+Object.defineProperty(globalThis, 'location', {
+  value: { origin: 'http://localhost:3000' },
+  configurable: true,
+});
diff --git a/frontend/src/__tests__/useFeedCreation.contract.test.ts b/frontend/src/__tests__/useFeedCreation.contract.test.ts
deleted file mode 100644
index 50027773..00000000
--- a/frontend/src/__tests__/useFeedCreation.contract.test.ts
+++ /dev/null
@@ -1,172 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { renderHook, act, waitFor } from '@testing-library/preact';
-import { http, HttpResponse } from 'msw';
-import { server, buildFeedResponse, buildStructuredErrorResponse } from './mocks/server';
-import { JSON_FEED_PREVIEW_PATH } from './mocks/apiFixtures';
-import { useFeedCreation } from '../feed';
-
-describe('useFeedCreation contract', () => {
-  it('sends feed creation requests with bearer auth and hydrates preview from json_public_url', async () => {
-    let receivedAuthorization: string | undefined;
-
-    server.use(
-      http.post('/api/v1/feeds', async ({ request }) => {
-        const body = (await request.json()) as { url: string };
-        receivedAuthorization = request.headers.get('authorization');
-
-        expect(body).toEqual({ url: 'https://example.com/articles' });
-
-        return HttpResponse.json(
-          buildFeedResponse({
-            url: body.url,
-            feed_token: 'generated-token',
-            public_url: '/api/v1/feeds/generated-token',
-            json_public_url: '/api/v1/feeds/generated-token.json',
-          }),
-          { status: 201 }
-        );
-      })
-    );
-
-    const { result } = renderHook(() => useFeedCreation());
-
-    await act(async () => {
-      await result.current.createFeed('https://example.com/articles', 'test-token-123');
-    });
-
-    expect(receivedAuthorization).toBe('Bearer test-token-123');
-    expect(result.current.error).toBeUndefined();
-    expect(result.current.result?.feed.feed_token).toBe('generated-token');
-    await waitFor(() => expect(result.current.result?.preview.status).toBe('preview_ready'));
-    expect(result.current.result?.preview.items[0]?.title).toBe('Sample preview item');
-  });
-
-  it('propagates structured auth failures without parsing the message text', async () => {
-    server.use(
-      http.post('/api/v1/feeds', async () =>
-        HttpResponse.json(
-          buildStructuredErrorResponse({
-            code: 'UNAUTHORIZED',
-            message: 'Authentication required',
-            kind: 'auth',
-            retryable: false,
-            next_action: 'enter_token',
-            retry_action: 'none',
-          }),
-          { status: 401 }
-        )
-      )
-    );
-
-    const { result } = renderHook(() => useFeedCreation());
-
-    await act(async () => {
-      await expect(result.current.createFeed('https://example.com/articles', 'token')).rejects.toMatchObject({
-        message: 'Authentication required',
-      });
-    });
-
-    expect(result.current.result).toBeUndefined();
-    expect(result.current.error).toMatchObject({
-      kind: 'auth',
-      code: 'UNAUTHORIZED',
-      nextAction: 'enter_token',
-      retryAction: 'none',
-      retryable: false,
-      message: 'Authentication required',
-    });
-  });
-
-  it('treats extraction-empty failures as corrective input errors without strategy metadata', async () => {
-    server.use(
-      http.post('/api/v1/feeds', async () =>
-        HttpResponse.json(
-          buildStructuredErrorResponse({
-            code: 'NO_FEED_ITEMS_EXTRACTED',
-            message: 'Could not extract feed items. Try a more specific listing URL or explicit selectors.',
-            kind: 'input',
-            retryable: false,
-            next_action: 'correct_input',
-            retry_action: 'none',
-          }),
-          { status: 422 }
-        )
-      )
-    );
-
-    const { result } = renderHook(() => useFeedCreation());
-
-    await act(async () => {
-      await expect(result.current.createFeed('https://example.com/articles', 'token')).rejects.toMatchObject({
-        kind: 'input',
-        code: 'NO_FEED_ITEMS_EXTRACTED',
-        nextAction: 'correct_input',
-        retryAction: 'none',
-        retryable: false,
-        message: 'Could not extract feed items. Try a more specific listing URL or explicit selectors.',
-      });
-    });
-  });
-
-  it('marks preview failure from the feed json response without status polling', async () => {
-    server.use(
-      http.post('/api/v1/feeds', async ({ request }) => {
-        const body = (await request.json()) as { url: string };
-
-        return HttpResponse.json(
-          buildFeedResponse({
-            url: body.url,
-            feed_token: 'generated-token',
-            public_url: '/api/v1/feeds/generated-token',
-            json_public_url: '/api/v1/feeds/generated-token.json',
-          }),
-          { status: 201 }
-        );
-      }),
-      http.get(JSON_FEED_PREVIEW_PATH, () => HttpResponse.text('No feed items', { status: 422 }))
-    );
-
-    const { result } = renderHook(() => useFeedCreation());
-
-    await act(async () => {
-      await result.current.createFeed('https://example.com/articles', 'token');
-    });
-
-    await waitFor(() => {
-      expect(result.current.result?.preview.status).toBe('preview_failed');
-      expect(result.current.result?.warnings[0]?.code).toBe('PREVIEW_HTTP_422');
-    });
-  });
-
-  it('rejects camelCase-only create payloads to enforce canonical snake_case contract', async () => {
-    server.use(
-      http.post('/api/v1/feeds', async () =>
-        HttpResponse.json(
-          {
-            success: true,
-            data: {
-              feed: {
-                id: 'feed-1',
-                name: 'Example Feed',
-                url: 'https://example.com/articles',
-                feedToken: 'generated-token',
-                publicUrl: '/api/v1/feeds/generated-token',
-                jsonPublicUrl: '/api/v1/feeds/generated-token.json',
-              },
-            },
-          },
-          { status: 201 }
-        )
-      )
-    );
-
-    const { result } = renderHook(() => useFeedCreation());
-
-    await act(async () => {
-      await expect(result.current.createFeed('https://example.com/articles', 'token')).rejects.toMatchObject({
-        kind: 'server',
-        code: 'INVALID_RESPONSE',
-      });
-    });
-  });
-});
diff --git a/frontend/src/__tests__/useFeedCreation.test.ts b/frontend/src/__tests__/useFeedCreation.test.ts
index 99e07793..844a9479 100644
--- a/frontend/src/__tests__/useFeedCreation.test.ts
+++ b/frontend/src/__tests__/useFeedCreation.test.ts
@@ -1,7 +1,7 @@
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import { renderHook, act, waitFor } from '@testing-library/preact';
 import { http, HttpResponse } from 'msw';
-import { server, buildFeedResponse } from './mocks/server';
+import { server, buildFeedResponse, buildStructuredErrorResponse } from './mocks/server';
 import { JSON_FEED_PREVIEW_PATH, jsonPreviewItems } from './mocks/apiFixtures';
 import { useFeedCreation } from '../feed';
 
@@ -190,4 +190,68 @@ describe('useFeedCreation', () => {
     expect(result.current.result?.preview.items[0]?.imageUrl).toBe('https://cdn.example/a.jpg');
     expect(result.current.result?.preview.items[1]).not.toHaveProperty('imageUrl');
   });
+
+  it('rejects camelCase-only create payloads to enforce canonical snake_case', async () => {
+    server.use(
+      http.post('/api/v1/feeds', () =>
+        HttpResponse.json(
+          {
+            success: true,
+            data: {
+              feed: {
+                id: 'feed-1',
+                name: 'Example Feed',
+                url: 'https://example.com/articles',
+                feedToken: 'generated-token',
+                publicUrl: '/api/v1/feeds/generated-token',
+                jsonPublicUrl: '/api/v1/feeds/generated-token.json',
+              },
+            },
+          },
+          { status: 201 }
+        )
+      )
+    );
+
+    const { result } = renderHook(() => useFeedCreation());
+
+    await act(async () => {
+      await expect(result.current.createFeed('https://example.com/articles', 'token')).rejects.toMatchObject({
+        kind: 'server',
+        code: 'INVALID_RESPONSE',
+      });
+    });
+  });
+
+  it('propagates structured auth failures without parsing the message text', async () => {
+    server.use(
+      http.post('/api/v1/feeds', () =>
+        HttpResponse.json(
+          buildStructuredErrorResponse({
+            code: 'UNAUTHORIZED',
+            message: 'Authentication required',
+            kind: 'auth',
+            retryable: false,
+            next_action: 'enter_token',
+            retry_action: 'none',
+          }),
+          { status: 401 }
+        )
+      )
+    );
+
+    const { result } = renderHook(() => useFeedCreation());
+
+    await act(async () => {
+      await expect(result.current.createFeed('https://example.com/articles', 'token')).rejects.toMatchObject({
+        message: 'Authentication required',
+      });
+    });
+
+    expect(result.current.error).toMatchObject({
+      kind: 'auth',
+      code: 'UNAUTHORIZED',
+      nextAction: 'enter_token',
+    });
+  });
 });
diff --git a/frontend/src/__tests__/useStudio.test.ts b/frontend/src/__tests__/useStudio.test.ts
index 684b2460..2364858a 100644
--- a/frontend/src/__tests__/useStudio.test.ts
+++ b/frontend/src/__tests__/useStudio.test.ts
@@ -34,18 +34,18 @@ async function advancePreview(ms = STUDIO_PREVIEW_SETTLE_MS) {
 function useStudioHandlers() {
   let validateCount = 0;
   let previewCount = 0;
-  let lastValidateAuth: string | null = null;
+  let lastValidateAuth: string | undefined;
 
   server.use(
-    http.post('/api/v1/feeds/suggest_selectors', () => HttpResponse.json(suggestSuccessBody('article', false))),
+    http.post('/api/v1/feeds/suggest_selectors', () =>
+      HttpResponse.json(suggestSuccessBody('article', false))
+    ),
     http.post('/api/v1/feeds/validate', async ({ request }) => {
       validateCount += 1;
-      lastValidateAuth = request.headers.get('authorization');
+      lastValidateAuth = request.headers.get('authorization') ?? undefined;
       const body = (await request.json()) as { selectors?: unknown; url?: string };
       const selectors = body.selectors ?? { items: { selector: 'a[href]' } };
-      return HttpResponse.json(
-        validateSuccessBody(selectors, validateYamlForSelectors(selectors, body.url))
-      );
+      return HttpResponse.json(validateSuccessBody(selectors, validateYamlForSelectors(selectors, body.url)));
     }),
     http.post('/api/v1/feeds/preview', () => {
       previewCount += 1;
diff --git a/frontend/src/api/http/client.ts b/frontend/src/api/http/client.ts
index c48af0e1..3ca08489 100644
--- a/frontend/src/api/http/client.ts
+++ b/frontend/src/api/http/client.ts
@@ -12,7 +12,8 @@ type SdkFields = {
 
 /** Same-origin JSON API prefix. Absolute when `location.origin` exists so `Request` can parse it. */
 export function jsonBaseUrl(): string {
-  return location.origin ? `${location.origin}/api/v1` : '/api/v1';
+  const origin = globalThis.location?.origin;
+  return origin ? `${origin}/api/v1` : '/api/v1';
 }
 
 /**
diff --git a/frontend/src/components/Bookmarklet.tsx b/frontend/src/components/Bookmarklet.tsx
index 86af64c3..e8b63ca5 100644
--- a/frontend/src/components/Bookmarklet.tsx
+++ b/frontend/src/components/Bookmarklet.tsx
@@ -1,21 +1,12 @@
-import { buildAppRouteHref } from '../routes/appRoute';
+import { buildBookmarkletHref } from '../routes/bookmarkletHref';
 import { COPY } from '../journey/copy';
 
 export function Bookmarklet({ onClick }: { onClick?: (event: Event) => void }) {
-  const bookmarkletHref = (() => {
-    if (globalThis.window === undefined) return '#';
-
-    const createHref = buildAppRouteHref({ kind: 'create' });
-    const targetPrefix = `${createHref}?url=`;
-
-    return `javascript:window.location.assign(${JSON.stringify(targetPrefix)}+encodeURIComponent(window.location.href));`;
-  })();
-
   return (
     <a
       id="bookmarklet"
       class="utility-link"
-      href={bookmarkletHref}
+      href={buildBookmarkletHref()}
       title={COPY.bookmarkletDragHint}
       onClick={(event) => {
         onClick?.(event);
diff --git a/frontend/src/routes/bookmarkletHref.ts b/frontend/src/routes/bookmarkletHref.ts
new file mode 100644
index 00000000..f10e76b0
--- /dev/null
+++ b/frontend/src/routes/bookmarkletHref.ts
@@ -0,0 +1,14 @@
+import { buildAppRouteHref } from './appRoute';
+
+/**
+ * Builds the `javascript:` bookmarklet href that opens create with the current page URL.
+ * @param baseHref - Origin used for the create route (defaults to the current location).
+ * @returns Bookmarklet href, or `#` when `window` is unavailable.
+ */
+export function buildBookmarkletHref(baseHref?: string): string {
+  if (globalThis.window === undefined && baseHref === undefined) return '#';
+
+  const createHref = buildAppRouteHref({ kind: 'create' }, baseHref);
+  const targetPrefix = `${createHref}?url=`;
+  return `javascript:window.location.assign(${JSON.stringify(targetPrefix)}+encodeURIComponent(window.location.href));`;
+}
diff --git a/frontend/tsconfig.json b/frontend/tsconfig.json
index 89eeff6b..986190e5 100644
--- a/frontend/tsconfig.json
+++ b/frontend/tsconfig.json
@@ -13,7 +13,7 @@
     "isolatedModules": true,
     "noEmit": true,
     "strict": true,
-    "types": ["vitest/globals", "@testing-library/jest-dom", "msw"]
+    "types": ["@testing-library/jest-dom", "msw"]
   },
   "include": ["src", "e2e", "playwright.config.ts", "vite.config.ts", "vitest*.ts", "vitest.config.js"]
 }
diff --git a/frontend/vitest.config.js b/frontend/vitest.config.js
index 3f4cab2c..a4a6a30b 100644
--- a/frontend/vitest.config.js
+++ b/frontend/vitest.config.js
@@ -1,13 +1,56 @@
 import { defineConfig, configDefaults } from 'vitest/config';
 
+const sharedExclude = [...configDefaults.exclude, 'tests/**', 'e2e/**'];
+
+const unitInclude = [
+  'src/__tests__/decideJourney.test.ts',
+  'src/__tests__/catalog.test.ts',
+  'src/__tests__/selectorDraft.test.ts',
+  'src/__tests__/url.test.ts',
+  'src/__tests__/feedCreationError.test.ts',
+  'src/__tests__/feedWorkflowStorage.test.ts',
+  'src/__tests__/studioService.test.ts',
+  'src/__tests__/previewHydration.test.ts',
+  'src/__tests__/apiHttp.*.test.ts',
+  'src/__tests__/persistentStorage.test.ts',
+  'src/__tests__/bookmarkletHref.test.ts',
+];
+
+const integrationInclude = [
+  'src/__tests__/App.integration.test.tsx',
+  'src/__tests__/ConfigStudio.test.tsx',
+  'src/__tests__/ResultDisplay.test.tsx',
+  'src/__tests__/useStudio.test.ts',
+  'src/__tests__/useFeedCreation.test.ts',
+  'src/__tests__/appRoute.test.ts',
+];
+
 export default defineConfig({
   test: {
-    environment: 'jsdom',
-    setupFiles: ['./src/__tests__/setup.ts'],
-    globals: true,
+    globals: false,
     testTimeout: 10_000,
     hookTimeout: 10_000,
-    exclude: [...configDefaults.exclude, 'tests/**', 'e2e/**'],
+    exclude: sharedExclude,
+    projects: [
+      {
+        extends: true,
+        test: {
+          name: 'unit',
+          environment: 'node',
+          include: unitInclude,
+          setupFiles: ['./src/__tests__/setup.unit.ts'],
+        },
+      },
+      {
+        extends: true,
+        test: {
+          name: 'integration',
+          environment: 'jsdom',
+          include: integrationInclude,
+          setupFiles: ['./src/__tests__/setup.ts'],
+        },
+      },
+    ],
   },
   esbuild: {
     jsx: 'automatic',
diff --git a/frontend/vitest.contract.config.ts b/frontend/vitest.contract.config.ts
deleted file mode 100644
index deea1c47..00000000
--- a/frontend/vitest.contract.config.ts
+++ /dev/null
@@ -1,8 +0,0 @@
-import { mergeConfig } from 'vitest/config';
-import baseConfig from './vitest.config.js';
-
-export default mergeConfig(baseConfig, {
-  test: {
-    include: ['src/__tests__/**/*.contract.test.*'],
-  },
-});
diff --git a/frontend/vitest.unit.config.ts b/frontend/vitest.unit.config.ts
deleted file mode 100644
index 2a54bdca..00000000
--- a/frontend/vitest.unit.config.ts
+++ /dev/null
@@ -1,8 +0,0 @@
-import { mergeConfig } from 'vitest/config';
-import baseConfig from './vitest.config.js';
-
-export default mergeConfig(baseConfig, {
-  test: {
-    exclude: [...(baseConfig.test?.exclude ?? []), 'src/__tests__/**/*.contract.test.*'],
-  },
-});

From efb7f81d87c3bee796b2c7e7a7a21db11974c2e8 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Tue, 22 Sep 2026 00:07:31 +0200
Subject: [PATCH 104/108] test(frontend): keep dialog inert and focus in
 Playwright

---
 frontend/e2e/fixtures.ts   | 108 ++++++++++++++++++++++++
 frontend/e2e/smoke.spec.ts | 163 +++++++++++--------------------------
 2 files changed, 156 insertions(+), 115 deletions(-)
 create mode 100644 frontend/e2e/fixtures.ts

diff --git a/frontend/e2e/fixtures.ts b/frontend/e2e/fixtures.ts
new file mode 100644
index 00000000..5db63a75
--- /dev/null
+++ b/frontend/e2e/fixtures.ts
@@ -0,0 +1,108 @@
+import { type Page, type Request } from '@playwright/test';
+import { COPY } from '../src/journey/copy';
+import {
+  createdFeedBody,
+  emptyCatalog,
+  metadataBody,
+  selectorsFromValidateRequest,
+  studioPreviewSuccessBody,
+  suggestSuccessBody,
+  validateSuccessBody,
+  validateYamlForSelectors,
+  type MetadataOptions,
+} from '../src/__tests__/mocks/apiFixtures';
+import { test as base, expect } from '@playwright/test';
+
+export const API_ROOT = /\/api\/v1\/?$/;
+export const API_CONFIGS = /\/api\/v1\/configs\/?$/;
+export const API_FEEDS = /\/api\/v1\/feeds\/?$/;
+export const API_VALIDATE = /\/api\/v1\/feeds\/validate\/?$/;
+export const API_SUGGEST = /\/api\/v1\/feeds\/suggest_selectors\/?$/;
+export const API_STUDIO_PREVIEW = /\/api\/v1\/feeds\/preview\/?$/;
+export const API_JSON_PREVIEW = /\/api\/v1\/feeds\/(?:generated-token|refined-token)\.json$/;
+
+export const EXAMPLE_URL = 'https://example.com/articles';
+
+type SpaFixtures = {
+  fulfillJson: (path: RegExp, body: unknown, status?: number, contentType?: string) => Promise<void>;
+  stubSpaApi: (options?: MetadataOptions) => Promise<void>;
+  stubStudioEndpoints: () => Promise<void>;
+  createReadyResult: (
+    options?: MetadataOptions & { stubFeedCreates?: (page: Page) => Promise<void> }
+  ) => Promise<void>;
+};
+
+export const test = base.extend<SpaFixtures>({
+  fulfillJson: async ({ page }, use) => {
+    await use(async (path, body, status = 200, contentType = 'application/json') => {
+      await page.route(path, async (route) => {
+        await route.fulfill({
+          status,
+          contentType,
+          body: JSON.stringify(body),
+        });
+      });
+    });
+  },
+
+  stubSpaApi: async ({ fulfillJson }, use) => {
+    await use(async (options: MetadataOptions = {}) => {
+      const isCatalogEnabled = options.isCatalogEnabled ?? true;
+      await fulfillJson(API_ROOT, metadataBody(options));
+      if (isCatalogEnabled) await fulfillJson(API_CONFIGS, emptyCatalog);
+    });
+  },
+
+  stubStudioEndpoints: async ({ page, fulfillJson }, use) => {
+    await use(async () => {
+      await page.route(API_VALIDATE, async (route) => {
+        const posted = route.request().postDataJSON() as unknown;
+        const selectors = selectorsFromValidateRequest(posted);
+        const body = validateSuccessBody(selectors, validateYamlForSelectors(selectors));
+        await route.fulfill({
+          status: 200,
+          contentType: 'application/json',
+          body: JSON.stringify(body),
+        });
+      });
+      await fulfillJson(API_SUGGEST, suggestSuccessBody('article', false));
+      await fulfillJson(API_STUDIO_PREVIEW, studioPreviewSuccessBody());
+    });
+  },
+
+  createReadyResult: async ({ page, fulfillJson, stubSpaApi, stubStudioEndpoints }, use) => {
+    await use(async (options = {}) => {
+      const { stubFeedCreates, ...metadataOptions } = options;
+      await stubSpaApi({ isCatalogEnabled: false, ...metadataOptions });
+      if (metadataOptions.isStudioEnabled !== false) await stubStudioEndpoints();
+      if (stubFeedCreates) {
+        await stubFeedCreates(page);
+      } else {
+        await fulfillJson(API_FEEDS, createdFeedBody(), 201);
+      }
+      await fulfillJson(API_JSON_PREVIEW, { items: [] }, 200, 'application/feed+json');
+      await page.addInitScript(() => {
+        localStorage.setItem('html2rss_access_token', 'token-123');
+      });
+      await page.goto('/');
+      await page.getByLabel(COPY.urlLabel).fill(EXAMPLE_URL);
+      await page.getByRole('button', { name: COPY.createFeed }).click();
+      await expect(page.getByText(COPY.feedReady)).toBeVisible();
+    });
+  },
+});
+
+export { expect };
+
+export function isSameOriginApi(url: string, path: RegExp): boolean {
+  const requested = new URL(url);
+  return path.test(requested.pathname) && requested.host !== 'api.html2rss.dev';
+}
+
+export function collectPosts(page: Page, path: RegExp, bag: Request[]) {
+  page.on('request', (request) => {
+    if (request.method() === 'POST' && isSameOriginApi(request.url(), path)) {
+      bag.push(request);
+    }
+  });
+}
diff --git a/frontend/e2e/smoke.spec.ts b/frontend/e2e/smoke.spec.ts
index ba9d8b2c..a5aad8e9 100644
--- a/frontend/e2e/smoke.spec.ts
+++ b/frontend/e2e/smoke.spec.ts
@@ -1,108 +1,26 @@
-import { expect, test, type Page, type Request } from '@playwright/test';
+import { type Request } from '@playwright/test';
 import { COPY } from '../src/journey/copy';
+import { createdFeedBody, jsonPreviewItems } from '../src/__tests__/mocks/apiFixtures';
 import {
-  createdFeedBody,
-  emptyCatalog,
-  jsonPreviewItems,
-  metadataBody,
-  selectorsFromValidateRequest,
-  studioPreviewSuccessBody,
-  suggestSuccessBody,
-  validateSuccessBody,
-  validateYamlForSelectors,
-  type MetadataOptions,
-} from '../src/__tests__/mocks/apiFixtures';
-
-const API_ROOT = /\/api\/v1\/?$/;
-const API_CONFIGS = /\/api\/v1\/configs\/?$/;
-const API_FEEDS = /\/api\/v1\/feeds\/?$/;
-const API_VALIDATE = /\/api\/v1\/feeds\/validate\/?$/;
-const API_SUGGEST = /\/api\/v1\/feeds\/suggest_selectors\/?$/;
-const API_STUDIO_PREVIEW = /\/api\/v1\/feeds\/preview\/?$/;
-const API_JSON_PREVIEW = /\/api\/v1\/feeds\/(?:generated-token|refined-token)\.json$/;
-
-const EXAMPLE_URL = 'https://example.com/articles';
-
-async function fulfillJson(
-  page: Page,
-  path: RegExp,
-  body: unknown,
-  status = 200,
-  contentType = 'application/json'
-) {
-  await page.route(path, async (route) => {
-    await route.fulfill({
-      status,
-      contentType,
-      body: JSON.stringify(body),
-    });
-  });
-}
-
-async function stubSpaApi(page: Page, options: MetadataOptions = {}) {
-  const isCatalogEnabled = options.isCatalogEnabled ?? true;
-  await fulfillJson(page, API_ROOT, metadataBody(options));
-  if (isCatalogEnabled) await fulfillJson(page, API_CONFIGS, emptyCatalog);
-}
-
-function isSameOriginApi(url: string, path: RegExp): boolean {
-  const requested = new URL(url);
-  return path.test(requested.pathname) && requested.host !== 'api.html2rss.dev';
-}
-
-async function stubStudioEndpoints(page: Page) {
-  await page.route(API_VALIDATE, async (route) => {
-    const request = route.request();
-    const posted = request.postDataJSON() as unknown;
-    const selectors = selectorsFromValidateRequest(posted);
-    const body = validateSuccessBody(selectors, validateYamlForSelectors(selectors));
-    await route.fulfill({
-      status: 200,
-      contentType: 'application/json',
-      body: JSON.stringify(body),
-    });
-  });
-  await fulfillJson(page, API_SUGGEST, suggestSuccessBody('article', false));
-  await fulfillJson(page, API_STUDIO_PREVIEW, studioPreviewSuccessBody());
-}
-
-async function createReadyResult(
-  page: Page,
-  options: MetadataOptions & { stubFeedCreates?: (page: Page) => Promise<void> } = {}
-) {
-  const { stubFeedCreates, ...metadataOptions } = options;
-  await stubSpaApi(page, { isCatalogEnabled: false, ...metadataOptions });
-  if (metadataOptions.isStudioEnabled !== false) await stubStudioEndpoints(page);
-  if (stubFeedCreates) {
-    await stubFeedCreates(page);
-  } else {
-    await fulfillJson(page, API_FEEDS, createdFeedBody(), 201);
-  }
-  await fulfillJson(page, API_JSON_PREVIEW, { items: [] }, 200, 'application/feed+json');
-  await page.addInitScript(() => {
-    localStorage.setItem('html2rss_access_token', 'token-123');
-  });
-  await page.goto('/');
-  await page.getByLabel(COPY.urlLabel).fill(EXAMPLE_URL);
-  await page.getByRole('button', { name: COPY.createFeed }).click();
-  await expect(page.getByText(COPY.feedReady)).toBeVisible();
-}
-
-function collectPosts(page: Page, path: RegExp, bag: Request[]) {
-  page.on('request', (request) => {
-    if (request.method() === 'POST' && isSameOriginApi(request.url(), path)) {
-      bag.push(request);
-    }
-  });
-}
+  API_CONFIGS,
+  API_FEEDS,
+  API_JSON_PREVIEW,
+  API_STUDIO_PREVIEW,
+  API_VALIDATE,
+  EXAMPLE_URL,
+  collectPosts,
+  expect,
+  isSameOriginApi,
+  test,
+} from './fixtures';
 
 test.describe('frontend smoke', () => {
-  test('loads create flow and inline access-token gate', async ({ page }) => {
+  test('loads create flow and inline access-token gate', async ({ page, stubSpaApi }) => {
     const catalogUrls: string[] = [];
     page.on('request', (request) => {
       if (API_CONFIGS.test(new URL(request.url()).pathname)) catalogUrls.push(request.url());
     });
-    await stubSpaApi(page);
+    await stubSpaApi();
 
     await page.goto('/');
 
@@ -119,7 +37,11 @@ test.describe('frontend smoke', () => {
     await expect(page.getByRole('button', { name: COPY.saveAndContinue })).toBeVisible();
     await expect(page.getByRole('button', { name: COPY.back })).toBeVisible();
     await expect(page.locator('dialog')).toHaveAttribute('open');
+    await expect(page.locator('#access-token')).toBeFocused();
     await expect(page.getByLabel(COPY.urlLabel)).toHaveCount(1);
+    expect(
+      await page.getByLabel(COPY.urlLabel).evaluate((element) => element.closest('[inert]') !== null)
+    ).toBe(true);
     await expect(page.getByText(COPY.createFailedTitle, { exact: true })).toHaveCount(0);
     await expect(page.getByText(COPY.createFailedRetryTitle, { exact: true })).toHaveCount(0);
 
@@ -130,10 +52,13 @@ test.describe('frontend smoke', () => {
     await expect(page.getByLabel(COPY.utilities)).toBeVisible();
   });
 
-  test('remounts create from BrandLockup and hashbang and clears creation chrome', async ({ page }) => {
-    await stubSpaApi(page, { isTokenRequired: false });
+  test('remounts create from BrandLockup and hashbang and clears creation chrome', async ({
+    page,
+    stubSpaApi,
+    fulfillJson,
+  }) => {
+    await stubSpaApi({ isTokenRequired: false });
     await fulfillJson(
-      page,
       API_FEEDS,
       {
         success: false,
@@ -172,11 +97,16 @@ test.describe('frontend smoke', () => {
     await expect(page.getByLabel(COPY.urlLabel)).toBeFocused();
   });
 
-  test('shows result after successful feed creation and realigns a stale result hash', async ({ page }) => {
-    await stubSpaApi(page);
-    await stubStudioEndpoints(page);
-    await fulfillJson(page, API_FEEDS, createdFeedBody(), 201);
-    await fulfillJson(page, API_JSON_PREVIEW, jsonPreviewItems, 200, 'application/feed+json');
+  test('shows result after successful feed creation and realigns a stale result hash', async ({
+    page,
+    stubSpaApi,
+    stubStudioEndpoints,
+    fulfillJson,
+  }) => {
+    await stubSpaApi();
+    await stubStudioEndpoints();
+    await fulfillJson(API_FEEDS, createdFeedBody(), 201);
+    await fulfillJson(API_JSON_PREVIEW, jsonPreviewItems, 200, 'application/feed+json');
 
     await page.addInitScript(() => {
       localStorage.setItem('html2rss_access_token', 'token-123');
@@ -216,8 +146,8 @@ test.describe('frontend smoke', () => {
     await expect(page.getByText(COPY.feedReady)).toBeVisible();
   });
 
-  test('recovers an empty result deep link onto create', async ({ page }) => {
-    await stubSpaApi(page, { isCatalogEnabled: false });
+  test('recovers an empty result deep link onto create', async ({ page, stubSpaApi }) => {
+    await stubSpaApi({ isCatalogEnabled: false });
 
     await page.goto('/#/result/missing-token');
 
@@ -227,8 +157,8 @@ test.describe('frontend smoke', () => {
     await expect(page.locator('.result-recovery')).toHaveCount(0);
   });
 
-  test('treats a refine hash as create', async ({ page }) => {
-    await stubSpaApi(page, { isCatalogEnabled: false });
+  test('treats a refine hash as create', async ({ page, stubSpaApi }) => {
+    await stubSpaApi({ isCatalogEnabled: false });
 
     await page.goto('/#/refine');
 
@@ -237,7 +167,10 @@ test.describe('frontend smoke', () => {
     await expect(page.getByRole('heading', { name: COPY.refineSelectors })).toHaveCount(0);
   });
 
-  test('refines a result in place and generates the feed without a live scrape', async ({ page }) => {
+  test('refines a result in place and generates the feed without a live scrape', async ({
+    page,
+    createReadyResult,
+  }) => {
     const validateRequests: Request[] = [];
     const previewRequests: Request[] = [];
     collectPosts(page, API_VALIDATE, validateRequests);
@@ -246,7 +179,7 @@ test.describe('frontend smoke', () => {
     // First create keeps generated-token; studio save must mint a new token so the
     // unmatched-result effect cannot hide a bounce-to-create regression.
     let createCount = 0;
-    await createReadyResult(page, {
+    await createReadyResult({
       stubFeedCreates: async (readyPage) => {
         await readyPage.route(API_FEEDS, async (route) => {
           if (route.request().method() !== 'POST') {
@@ -323,8 +256,8 @@ test.describe('frontend smoke', () => {
     await expect(page.getByRole('button', { name: COPY.saveAndGenerate })).toBeEnabled();
   });
 
-  test('leaves a result when the hash is the retired refine route', async ({ page }) => {
-    await createReadyResult(page);
+  test('leaves a result when the hash is the retired refine route', async ({ page, createReadyResult }) => {
+    await createReadyResult();
 
     await page.evaluate(() => {
       location.hash = '#/refine';
@@ -335,8 +268,8 @@ test.describe('frontend smoke', () => {
     await expect(page.getByRole('heading', { name: COPY.refineSelectors })).toHaveCount(0);
   });
 
-  test('hides refine when studio is disabled', async ({ page }) => {
-    await createReadyResult(page, { isStudioEnabled: false });
+  test('hides refine when studio is disabled', async ({ page, createReadyResult }) => {
+    await createReadyResult({ isStudioEnabled: false });
 
     await expect(page.getByText(COPY.feedReady)).toBeVisible();
     await expect(page.getByRole('button', { name: COPY.refineSelectors })).toHaveCount(0);

From a31d22334db1fce3e74d756bf1028e6454162dc6 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Tue, 22 Sep 2026 00:08:55 +0200
Subject: [PATCH 105/108] fix(frontend): allow Playwright fixture use in ESLint

---
 frontend/e2e/fixtures.ts  | 7 +++----
 frontend/eslint.config.js | 7 +++++++
 2 files changed, 10 insertions(+), 4 deletions(-)

diff --git a/frontend/e2e/fixtures.ts b/frontend/e2e/fixtures.ts
index 5db63a75..388e415d 100644
--- a/frontend/e2e/fixtures.ts
+++ b/frontend/e2e/fixtures.ts
@@ -1,4 +1,4 @@
-import { type Page, type Request } from '@playwright/test';
+import { test as base, expect, type Page, type Request } from '@playwright/test';
 import { COPY } from '../src/journey/copy';
 import {
   createdFeedBody,
@@ -11,7 +11,8 @@ import {
   validateYamlForSelectors,
   type MetadataOptions,
 } from '../src/__tests__/mocks/apiFixtures';
-import { test as base, expect } from '@playwright/test';
+
+export { expect } from '@playwright/test';
 
 export const API_ROOT = /\/api\/v1\/?$/;
 export const API_CONFIGS = /\/api\/v1\/configs\/?$/;
@@ -92,8 +93,6 @@ export const test = base.extend<SpaFixtures>({
   },
 });
 
-export { expect };
-
 export function isSameOriginApi(url: string, path: RegExp): boolean {
   const requested = new URL(url);
   return path.test(requested.pathname) && requested.host !== 'api.html2rss.dev';
diff --git a/frontend/eslint.config.js b/frontend/eslint.config.js
index 3796ffdb..2b0a552c 100644
--- a/frontend/eslint.config.js
+++ b/frontend/eslint.config.js
@@ -51,5 +51,12 @@ export default tseslint.config(
     rules: {
       'no-restricted-imports': 'off',
     },
+  },
+  {
+    files: ['e2e/**/*.ts'],
+    rules: {
+      // Playwright fixtures expose a `use` callback that is not a React Hook.
+      'react-hooks/rules-of-hooks': 'off',
+    },
   }
 );

From 63ea727d4f35e673266f5ca0aceb0f36291d8d41 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Tue, 22 Sep 2026 00:13:40 +0200
Subject: [PATCH 106/108] test(frontend): cover token-to-create non-auth
 Decision chrome

---
 .../src/__tests__/App.integration.test.tsx    | 54 +++++++++++++++++++
 1 file changed, 54 insertions(+)

diff --git a/frontend/src/__tests__/App.integration.test.tsx b/frontend/src/__tests__/App.integration.test.tsx
index 775ed17b..d4a38a31 100644
--- a/frontend/src/__tests__/App.integration.test.tsx
+++ b/frontend/src/__tests__/App.integration.test.tsx
@@ -236,6 +236,19 @@ describe('App', () => {
     ]);
   });
 
+  it('clears the access token and remounts create on logout', async () => {
+    localStorage.setItem('html2rss_access_token', ACCESS_TOKEN);
+
+    const user = await renderApp();
+    await user.click(await screen.findByRole('button', { name: COPY.logout }));
+
+    expect(localStorage.getItem('html2rss_access_token')).toBeNull();
+    expect(sessionStorage.getItem('html2rss_access_token')).toBeNull();
+    expect(location.hash).toMatch(/^#\/create/);
+    expect(screen.queryByRole('button', { name: COPY.logout })).not.toBeInTheDocument();
+    expect(document.querySelector('.form-shell')).toHaveAttribute('data-state', 'create');
+  });
+
   it('prefills bookmarklet hash URLs over a saved draft', async () => {
     localStorage.setItem(
       'html2rss_feed_draft_state',
@@ -271,6 +284,47 @@ describe('App', () => {
     expect(sessionStorage.getItem('html2rss_access_token')).toBeNull();
   });
 
+  it('keeps Decision chrome when token save create fails non-auth onto create', async () => {
+    server.use(
+      http.post('/api/v1/feeds', () =>
+        HttpResponse.json(
+          buildStructuredErrorResponse({
+            message: 'Upstream failed',
+            kind: 'server',
+            retryable: true,
+            next_action: 'retry',
+            retry_action: 'primary',
+          }),
+          { status: 500 }
+        )
+      )
+    );
+
+    const user = await renderApp();
+    await user.type(screen.getByLabelText(COPY.urlLabel), EXAMPLE_URL);
+    await user.click(screen.getByRole('button', { name: COPY.createFeed }));
+
+    await screen.findByRole('heading', { name: COPY.tokenTitle });
+    await user.type(document.querySelector('#access-token') as HTMLInputElement, 'token-123');
+    await user.click(screen.getByRole('button', { name: COPY.saveAndContinue }));
+
+    await waitFor(() => {
+      expect(location.hash).toMatch(/^#\/create/);
+    });
+    await screen.findByText(COPY.createFailedRetryTitle);
+    expect(screen.getByText('Upstream failed')).toBeInTheDocument();
+    expect(screen.queryByRole('heading', { name: COPY.tokenTitle })).not.toBeInTheDocument();
+    expect(document.querySelector('.form-shell')).toHaveAttribute('data-state', 'error');
+
+    // Remount from token→create must keep Decision error (hasAutoSubmitted blocks wipe/auto-retry).
+    await waitFor(() => {
+      expect(screen.getByText(COPY.createFailedRetryTitle)).toBeInTheDocument();
+      expect(screen.getByText('Upstream failed')).toBeInTheDocument();
+      expect(location.hash).toMatch(/^#\/create/);
+      expect(document.querySelector('.form-shell')).toHaveAttribute('data-state', 'error');
+    });
+  });
+
   it('reopens the token gate on auth rejection and ignores non-token forbidden', async () => {
     localStorage.setItem('html2rss_access_token', ACCESS_TOKEN);
     server.use(

From 043164002da47a8c7c87ad1f1122f13712229068 Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Tue, 22 Sep 2026 00:16:49 +0200
Subject: [PATCH 107/108] test(frontend): unify HTTP adapter tests

Collapse four fetch-spy suites into one module with a Request reader that
fails closed, and reuse shared fixtures for metadata and catalog bodies.
---
 .../src/__tests__/apiHttp.catalog.test.ts     |  37 -----
 frontend/src/__tests__/apiHttp.client.test.ts |  45 ------
 frontend/src/__tests__/apiHttp.feeds.test.ts  |  94 -----------
 .../src/__tests__/apiHttp.metadata.test.ts    |  43 -----
 frontend/src/__tests__/apiHttp.test.ts        | 150 ++++++++++++++++++
 frontend/vitest.config.js                     |   2 +-
 6 files changed, 151 insertions(+), 220 deletions(-)
 delete mode 100644 frontend/src/__tests__/apiHttp.catalog.test.ts
 delete mode 100644 frontend/src/__tests__/apiHttp.client.test.ts
 delete mode 100644 frontend/src/__tests__/apiHttp.feeds.test.ts
 delete mode 100644 frontend/src/__tests__/apiHttp.metadata.test.ts
 create mode 100644 frontend/src/__tests__/apiHttp.test.ts

diff --git a/frontend/src/__tests__/apiHttp.catalog.test.ts b/frontend/src/__tests__/apiHttp.catalog.test.ts
deleted file mode 100644
index a6eb2f4f..00000000
--- a/frontend/src/__tests__/apiHttp.catalog.test.ts
+++ /dev/null
@@ -1,37 +0,0 @@
-import { afterEach, describe, expect, it, vi } from 'vitest';
-import { httpRequestUrl } from '../api/http/client';
-import { requestConfigCatalog } from '../api/http/catalog';
-
-const catalogBody = {
-  success: true,
-  data: { configs: [] },
-  meta: { total: 0, catalog_version: 2, starters: [] },
-};
-
-describe('requestConfigCatalog', () => {
-  afterEach(() => {
-    vi.restoreAllMocks();
-  });
-
-  it('loads GET /configs through the generated client and ignores catalog.url', async () => {
-    const fetchMock = vi.spyOn(globalThis, 'fetch').mockResolvedValue(Response.json(catalogBody));
-
-    const payload = await requestConfigCatalog();
-    const input = fetchMock.mock.calls[0]?.[0];
-    expect(input).toBeInstanceOf(Request);
-    if (!(input instanceof Request)) return;
-
-    const requested = httpRequestUrl(input);
-    expect(requested.host).not.toBe('api.html2rss.dev');
-    expect(requested.pathname).toBe('/api/v1/configs');
-    expect(payload).toMatchObject({ success: true, meta: { catalog_version: 2 } });
-  });
-
-  it('returns undefined when the catalog is disabled', async () => {
-    vi.spyOn(globalThis, 'fetch').mockResolvedValue(
-      Response.json({ error: 'catalog_disabled' }, { status: 404 })
-    );
-
-    await expect(requestConfigCatalog()).resolves.toBeUndefined();
-  });
-});
diff --git a/frontend/src/__tests__/apiHttp.client.test.ts b/frontend/src/__tests__/apiHttp.client.test.ts
deleted file mode 100644
index 6ab95e52..00000000
--- a/frontend/src/__tests__/apiHttp.client.test.ts
+++ /dev/null
@@ -1,45 +0,0 @@
-import { afterEach, describe, expect, it, vi } from 'vitest';
-import { getApiMetadata } from '../api/generated/sdk.gen';
-import { httpRequestUrl, jsonBaseUrl, unwrap } from '../api/http/client';
-
-describe('generated OpenAPI client', () => {
-  afterEach(() => {
-    vi.restoreAllMocks();
-  });
-
-  it('pins requests to same-origin /api/v1 and never api.html2rss.dev', async () => {
-    const fetchMock = vi.spyOn(globalThis, 'fetch').mockResolvedValue(
-      Response.json({
-        success: true,
-        data: {
-          api: { name: 'html2rss-web API', description: 'd', openapi_url: '/openapi.yaml' },
-          instance: { feed_creation: { enabled: true, access_token_required: true } },
-        },
-      })
-    );
-
-    const envelope = await unwrap(getApiMetadata({ baseUrl: jsonBaseUrl() }));
-    const input = fetchMock.mock.calls[0]?.[0];
-    expect(input).toBeInstanceOf(Request);
-    if (!(input instanceof Request)) return;
-
-    const requested = httpRequestUrl(input);
-    expect(requested.host).not.toBe('api.html2rss.dev');
-    expect(requested.pathname).toMatch(/^\/api\/v1\/?$/);
-    expect(envelope).toMatchObject({ ok: true, status: 200 });
-    expect(envelope.body).toMatchObject({ success: true });
-  });
-
-  it('unwraps HTTP errors into ok/status/body without throwing', async () => {
-    vi.spyOn(globalThis, 'fetch').mockResolvedValue(
-      Response.json({ error: 'catalog_disabled' }, { status: 404 })
-    );
-
-    const envelope = await unwrap(getApiMetadata({ baseUrl: jsonBaseUrl() }));
-    expect(envelope).toMatchObject({
-      ok: false,
-      status: 404,
-      body: { error: 'catalog_disabled' },
-    });
-  });
-});
diff --git a/frontend/src/__tests__/apiHttp.feeds.test.ts b/frontend/src/__tests__/apiHttp.feeds.test.ts
deleted file mode 100644
index 355d1d85..00000000
--- a/frontend/src/__tests__/apiHttp.feeds.test.ts
+++ /dev/null
@@ -1,94 +0,0 @@
-import { afterEach, describe, expect, it, vi } from 'vitest';
-import { httpRequestUrl } from '../api/http/client';
-import { postCreateFeed, postPreviewFeed, postSuggestSelectors, postValidateFeed } from '../api/http/feeds';
-
-const createdFeed = {
-  success: true,
-  data: {
-    feed: {
-      id: 'feed-1',
-      name: 'Example',
-      url: 'https://example.com',
-      feed_token: 'tok',
-      public_url: '/api/v1/feeds/tok',
-      json_public_url: '/api/v1/feeds/tok.json',
-    },
-  },
-};
-
-describe('postCreateFeed', () => {
-  afterEach(() => {
-    vi.restoreAllMocks();
-  });
-
-  it('POSTs /feeds on the same origin and omits Authorization when the token is empty', async () => {
-    const fetchMock = vi
-      .spyOn(globalThis, 'fetch')
-      .mockResolvedValue(Response.json({ success: false, error: { code: 'UNAUTHORIZED' } }, { status: 401 }));
-
-    const envelope = await postCreateFeed('https://example.com', '  ');
-    const input = fetchMock.mock.calls[0]?.[0];
-    expect(input).toBeInstanceOf(Request);
-    if (!(input instanceof Request)) return;
-
-    const requested = httpRequestUrl(input);
-    expect(requested.host).not.toBe('api.html2rss.dev');
-    expect(requested.pathname).toBe('/api/v1/feeds');
-    expect(input.method).toBe('POST');
-    expect(input.headers.get('Authorization')).toBeNull();
-    expect(JSON.parse(await input.clone().text())).toEqual({ url: 'https://example.com' });
-    expect(envelope).toMatchObject({ ok: false, status: 401 });
-  });
-
-  it('sends Bearer auth and optional selectors through the generated client', async () => {
-    const fetchMock = vi
-      .spyOn(globalThis, 'fetch')
-      .mockResolvedValue(Response.json(createdFeed, { status: 201 }));
-    const selectors = {
-      items: { selector: 'article' },
-      title: { selector: 'h2', extractor: 'text' as const },
-    };
-
-    const envelope = await postCreateFeed('https://example.com/articles', 'token-123', selectors);
-    const input = fetchMock.mock.calls[0]?.[0];
-    expect(input).toBeInstanceOf(Request);
-    if (!(input instanceof Request)) return;
-
-    expect(httpRequestUrl(input).host).not.toBe('api.html2rss.dev');
-    expect(input.headers.get('Authorization')).toBe('Bearer token-123');
-    expect(JSON.parse(await input.clone().text())).toEqual({
-      url: 'https://example.com/articles',
-      selectors,
-    });
-    expect(envelope).toMatchObject({ ok: true, status: 201 });
-  });
-});
-
-describe('studio JSON writes', () => {
-  afterEach(() => {
-    vi.restoreAllMocks();
-  });
-
-  it('POSTs validate, preview, and suggest through the generated client', async () => {
-    const fetchMock = vi.spyOn(globalThis, 'fetch').mockResolvedValue(Response.json({ success: true }));
-    const selectors = { items: { selector: 'article' } };
-
-    await postValidateFeed('token-123', 'https://example.com', selectors);
-    await postPreviewFeed('token-123', 'https://example.com', selectors);
-    await postSuggestSelectors('token-123', 'https://example.com');
-
-    const paths = fetchMock.mock.calls.map((call) => {
-      const input = call[0];
-      expect(input).toBeInstanceOf(Request);
-      if (!(input instanceof Request)) return '';
-      expect(httpRequestUrl(input).host).not.toBe('api.html2rss.dev');
-      return httpRequestUrl(input).pathname;
-    });
-
-    expect(paths).toEqual([
-      '/api/v1/feeds/validate',
-      '/api/v1/feeds/preview',
-      '/api/v1/feeds/suggest_selectors',
-    ]);
-  });
-});
diff --git a/frontend/src/__tests__/apiHttp.metadata.test.ts b/frontend/src/__tests__/apiHttp.metadata.test.ts
deleted file mode 100644
index f227164a..00000000
--- a/frontend/src/__tests__/apiHttp.metadata.test.ts
+++ /dev/null
@@ -1,43 +0,0 @@
-import { afterEach, describe, expect, it, vi } from 'vitest';
-import { httpRequestUrl } from '../api/http/client';
-import { requestApiMetadata } from '../api/http/metadata';
-
-const metadataBody = {
-  success: true,
-  data: {
-    api: { name: 'html2rss-web API', description: 'd', openapi_url: '/openapi.yaml' },
-    instance: {
-      feed_creation: { enabled: true, access_token_required: true },
-      studio: { enabled: true },
-      catalog: { enabled: true, url: '/api/v1/configs' },
-    },
-  },
-};
-
-describe('requestApiMetadata', () => {
-  afterEach(() => {
-    vi.restoreAllMocks();
-  });
-
-  it('loads GET /api/v1 through the generated client on the same origin', async () => {
-    const fetchMock = vi.spyOn(globalThis, 'fetch').mockResolvedValue(Response.json(metadataBody));
-
-    const payload = await requestApiMetadata();
-    const input = fetchMock.mock.calls[0]?.[0];
-    expect(input).toBeInstanceOf(Request);
-    if (!(input instanceof Request)) return;
-
-    const requested = httpRequestUrl(input);
-    expect(requested.host).not.toBe('api.html2rss.dev');
-    expect(requested.pathname).toMatch(/^\/api\/v1\/?$/);
-    expect(payload?.data.instance.feed_creation.enabled).toBe(true);
-  });
-
-  it('returns undefined when instance is missing', async () => {
-    vi.spyOn(globalThis, 'fetch').mockResolvedValue(
-      Response.json({ success: true, data: { api: metadataBody.data.api } })
-    );
-
-    await expect(requestApiMetadata()).resolves.toBeUndefined();
-  });
-});
diff --git a/frontend/src/__tests__/apiHttp.test.ts b/frontend/src/__tests__/apiHttp.test.ts
new file mode 100644
index 00000000..11eaaab0
--- /dev/null
+++ b/frontend/src/__tests__/apiHttp.test.ts
@@ -0,0 +1,150 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { getApiMetadata } from '../api/generated/sdk.gen';
+import { httpRequestUrl, jsonBaseUrl, unwrap } from '../api/http/client';
+import { requestConfigCatalog } from '../api/http/catalog';
+import { postCreateFeed, postPreviewFeed, postSuggestSelectors, postValidateFeed } from '../api/http/feeds';
+import { requestApiMetadata } from '../api/http/metadata';
+import { createdFeedBody, emptyCatalog, metadataBody } from './mocks/apiFixtures';
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+function fetchRequest(fetchMock: ReturnType<typeof vi.spyOn>, callIndex = 0): Request {
+  const input = fetchMock.mock.calls[callIndex]?.[0];
+  if (!(input instanceof Request)) {
+    throw new Error(`expected fetch call ${callIndex} to receive a Request`);
+  }
+  return input;
+}
+
+describe('unwrap / same-origin client', () => {
+  it('pins requests to same-origin /api/v1 and never api.html2rss.dev', async () => {
+    const fetchMock = vi.spyOn(globalThis, 'fetch').mockResolvedValue(Response.json(metadataBody()));
+
+    const envelope = await unwrap(getApiMetadata({ baseUrl: jsonBaseUrl() }));
+    const requested = httpRequestUrl(fetchRequest(fetchMock));
+
+    expect(requested.host).not.toBe('api.html2rss.dev');
+    expect(requested.pathname).toMatch(/^\/api\/v1\/?$/);
+    expect(envelope).toMatchObject({ ok: true, status: 200, body: { success: true } });
+  });
+
+  it('unwraps HTTP errors into ok/status/body without throwing', async () => {
+    vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+      Response.json({ error: 'catalog_disabled' }, { status: 404 })
+    );
+
+    const envelope = await unwrap(getApiMetadata({ baseUrl: jsonBaseUrl() }));
+    expect(envelope).toMatchObject({
+      ok: false,
+      status: 404,
+      body: { error: 'catalog_disabled' },
+    });
+  });
+});
+
+describe('requestApiMetadata', () => {
+  it('loads GET /api/v1 through the generated client on the same origin', async () => {
+    const body = metadataBody();
+    const fetchMock = vi.spyOn(globalThis, 'fetch').mockResolvedValue(Response.json(body));
+
+    const payload = await requestApiMetadata();
+    const requested = httpRequestUrl(fetchRequest(fetchMock));
+
+    expect(requested.pathname).toMatch(/^\/api\/v1\/?$/);
+    expect(payload?.data.instance.feed_creation.enabled).toBe(true);
+  });
+
+  it('returns undefined when instance is missing', async () => {
+    const body = metadataBody();
+    vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+      Response.json({ success: true, data: { api: body.data.api } })
+    );
+
+    await expect(requestApiMetadata()).resolves.toBeUndefined();
+  });
+});
+
+describe('requestConfigCatalog', () => {
+  it('loads GET /configs through the generated client and ignores catalog.url', async () => {
+    const fetchMock = vi.spyOn(globalThis, 'fetch').mockResolvedValue(Response.json(emptyCatalog));
+
+    const payload = await requestConfigCatalog();
+    const requested = httpRequestUrl(fetchRequest(fetchMock));
+
+    expect(requested.host).not.toBe('api.html2rss.dev');
+    expect(requested.pathname).toBe('/api/v1/configs');
+    expect(payload).toMatchObject({ success: true, meta: { catalog_version: 2 } });
+  });
+
+  it('returns undefined when the catalog is disabled', async () => {
+    vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+      Response.json({ error: 'catalog_disabled' }, { status: 404 })
+    );
+
+    await expect(requestConfigCatalog()).resolves.toBeUndefined();
+  });
+});
+
+describe('postCreateFeed', () => {
+  it('POSTs /feeds on the same origin and omits Authorization when the token is empty', async () => {
+    const fetchMock = vi
+      .spyOn(globalThis, 'fetch')
+      .mockResolvedValue(Response.json({ success: false, error: { code: 'UNAUTHORIZED' } }, { status: 401 }));
+
+    const envelope = await postCreateFeed('https://example.com', '  ');
+    const input = fetchRequest(fetchMock);
+    const requested = httpRequestUrl(input);
+
+    expect(requested.pathname).toBe('/api/v1/feeds');
+    expect(input.method).toBe('POST');
+    expect(input.headers.get('Authorization')).toBeNull();
+    expect(JSON.parse(await input.clone().text())).toEqual({ url: 'https://example.com' });
+    expect(envelope).toMatchObject({ ok: false, status: 401 });
+  });
+
+  it('sends Bearer auth and optional selectors through the generated client', async () => {
+    const fetchMock = vi
+      .spyOn(globalThis, 'fetch')
+      .mockResolvedValue(
+        Response.json(
+          createdFeedBody({ feed_token: 'tok', id: 'feed-1', name: 'Example', url: 'https://example.com' }),
+          { status: 201 }
+        )
+      );
+    const selectors = {
+      items: { selector: 'article' },
+      title: { selector: 'h2', extractor: 'text' as const },
+    };
+
+    const envelope = await postCreateFeed('https://example.com/articles', 'token-123', selectors);
+    const input = fetchRequest(fetchMock);
+
+    expect(input.headers.get('Authorization')).toBe('Bearer token-123');
+    expect(JSON.parse(await input.clone().text())).toEqual({
+      url: 'https://example.com/articles',
+      selectors,
+    });
+    expect(envelope).toMatchObject({ ok: true, status: 201 });
+  });
+});
+
+describe('studio JSON writes', () => {
+  it('POSTs validate, preview, and suggest through the generated client', async () => {
+    const fetchMock = vi.spyOn(globalThis, 'fetch').mockResolvedValue(Response.json({ success: true }));
+    const selectors = { items: { selector: 'article' } };
+
+    await postValidateFeed('token-123', 'https://example.com', selectors);
+    await postPreviewFeed('token-123', 'https://example.com', selectors);
+    await postSuggestSelectors('token-123', 'https://example.com');
+
+    const paths = [0, 1, 2].map((index) => httpRequestUrl(fetchRequest(fetchMock, index)).pathname);
+
+    expect(paths).toEqual([
+      '/api/v1/feeds/validate',
+      '/api/v1/feeds/preview',
+      '/api/v1/feeds/suggest_selectors',
+    ]);
+  });
+});
diff --git a/frontend/vitest.config.js b/frontend/vitest.config.js
index a4a6a30b..8d379cb9 100644
--- a/frontend/vitest.config.js
+++ b/frontend/vitest.config.js
@@ -11,7 +11,7 @@ const unitInclude = [
   'src/__tests__/feedWorkflowStorage.test.ts',
   'src/__tests__/studioService.test.ts',
   'src/__tests__/previewHydration.test.ts',
-  'src/__tests__/apiHttp.*.test.ts',
+  'src/__tests__/apiHttp.test.ts',
   'src/__tests__/persistentStorage.test.ts',
   'src/__tests__/bookmarkletHref.test.ts',
 ];

From 07fbd7fbdb9e447e68580ffbbe98645d7656d18a Mon Sep 17 00:00:00 2001
From: Gil Desmarais <git@desmarais.de>
Date: Tue, 22 Sep 2026 00:17:30 +0200
Subject: [PATCH 108/108] test(frontend): drop duplicate preview and route
 cases

Keep preview HTTP semantics in the service suite, describe unknown hashes
as create, and fail closed on studio phase assertions.
---
 frontend/src/__tests__/appRoute.test.ts       | 49 ++++---------------
 .../src/__tests__/useFeedCreation.test.ts     | 47 ------------------
 frontend/src/__tests__/useStudio.test.ts      | 22 ++++-----
 3 files changed, 19 insertions(+), 99 deletions(-)

diff --git a/frontend/src/__tests__/appRoute.test.ts b/frontend/src/__tests__/appRoute.test.ts
index e1e877eb..40bcfd86 100644
--- a/frontend/src/__tests__/appRoute.test.ts
+++ b/frontend/src/__tests__/appRoute.test.ts
@@ -51,12 +51,16 @@ describe('appRoute', () => {
     ).toEqual({ kind: 'create', prefillUrl: 'https://example.com/articles' });
   });
 
-  it('canonicalizes hashbang create hashes to #/create and bumps createEntryKey', () => {
-    history.replaceState({}, '', 'http://localhost:3000/#!/create');
+  it('canonicalizes hashbang create hashes, preserves prefill, and bumps createEntryKey', () => {
+    history.replaceState({}, '', 'http://localhost:3000/#!/create?url=https%3A%2F%2Fexample.com%2Farticles');
 
     const { result, unmount } = renderHook(() => useAppRoute());
 
-    expect(location.hash).toBe('#/create');
+    expect(location.hash).toBe('#/create?url=https%3A%2F%2Fexample.com%2Farticles');
+    expect(result.current.route).toEqual({
+      kind: 'create',
+      prefillUrl: 'https://example.com/articles',
+    });
     expect(result.current.createEntryKey).toBeGreaterThan(0);
     unmount();
   });
@@ -76,49 +80,16 @@ describe('appRoute', () => {
     unmount();
   });
 
-  it('canonicalizes hashbang create hashes with a url query', () => {
-    history.replaceState({}, '', 'http://localhost:3000/#!/create?url=https%3A%2F%2Fexample.com%2Farticles');
-
-    const { result, unmount } = renderHook(() => useAppRoute());
-
-    expect(location.hash).toBe('#/create?url=https%3A%2F%2Fexample.com%2Farticles');
-    expect(result.current.route).toEqual({
-      kind: 'create',
-      prefillUrl: 'https://example.com/articles',
-    });
-    unmount();
-  });
-
-  it('reads a retired refine hash as create', () => {
+  it('treats an unknown hash as create and canonicalizes onto #/create', () => {
     expect(
       readAppRoute({
         pathname: '/',
         search: '',
-        hash: '#/refine?url=https%3A%2F%2Fexample.com',
+        hash: '#/unknown?url=https%3A%2F%2Fexample.com',
       })
     ).toEqual({ kind: 'create', prefillUrl: 'https://example.com' });
 
-    expect(
-      readAppRoute({
-        pathname: '/',
-        search: '',
-        hash: '#/refine/',
-      })
-    ).toEqual({ kind: 'create' });
-  });
-
-  it('canonicalizes a hashbang refine hash onto create', () => {
-    history.replaceState({}, '', 'http://localhost:3000/#!/refine');
-
-    const { result, unmount } = renderHook(() => useAppRoute());
-
-    expect(location.hash).toBe('#/create');
-    expect(result.current.route).toEqual({ kind: 'create' });
-    unmount();
-  });
-
-  it('canonicalizes a retired refine hash onto create', () => {
-    history.replaceState({}, '', 'http://localhost:3000/#/refine');
+    history.replaceState({}, '', 'http://localhost:3000/#/unknown');
 
     const { result, unmount } = renderHook(() => useAppRoute());
 
diff --git a/frontend/src/__tests__/useFeedCreation.test.ts b/frontend/src/__tests__/useFeedCreation.test.ts
index 844a9479..01d905ab 100644
--- a/frontend/src/__tests__/useFeedCreation.test.ts
+++ b/frontend/src/__tests__/useFeedCreation.test.ts
@@ -83,25 +83,6 @@ describe('useFeedCreation', () => {
     expect(previewAttempts).toBe(2);
   });
 
-  it('marks preview failed for non-transient preview responses', async () => {
-    useCreateFeedHandler();
-    server.use(http.get(JSON_FEED_PREVIEW_PATH, () => new HttpResponse('', { status: 422 })));
-
-    const { result } = renderHook(() => useFeedCreation());
-    await act(async () => {
-      await result.current.createFeed('https://example.com/articles', 'token-123');
-    });
-
-    await waitFor(() => {
-      expect(result.current.result?.preview.status).toBe('preview_failed');
-      expect(result.current.result?.warnings[0]).toMatchObject({
-        code: 'PREVIEW_HTTP_422',
-        retryable: false,
-        nextAction: 'wait',
-      });
-    });
-  });
-
   it('retries preview without recreating the feed', async () => {
     const createCount = useCreateFeedHandler();
     let previewAttempts = 0;
@@ -163,34 +144,6 @@ describe('useFeedCreation', () => {
     expect(result.current.result?.preview.items[0]).not.toHaveProperty('imageUrl');
   });
 
-  it('uses member richness when creation had an access token', async () => {
-    useCreateFeedHandler();
-    server.use(
-      http.get(JSON_FEED_PREVIEW_PATH, () =>
-        HttpResponse.json(
-          {
-            items: [
-              { title: 'Shown', image: 'https://cdn.example/a.jpg' },
-              { title: 'Unsafe', image: 'javascript:alert(1)' },
-              ...Array.from({ length: 10 }, (_, index) => ({ title: `Extra ${index}` })),
-            ],
-          },
-          { headers: { 'content-type': 'application/feed+json' } }
-        )
-      )
-    );
-
-    const { result } = renderHook(() => useFeedCreation());
-    await act(async () => {
-      await result.current.createFeed('https://example.com/articles', 'token-123');
-    });
-
-    await waitFor(() => expect(result.current.result?.preview.status).toBe('preview_ready'));
-    expect(result.current.result?.preview.items).toHaveLength(10);
-    expect(result.current.result?.preview.items[0]?.imageUrl).toBe('https://cdn.example/a.jpg');
-    expect(result.current.result?.preview.items[1]).not.toHaveProperty('imageUrl');
-  });
-
   it('rejects camelCase-only create payloads to enforce canonical snake_case', async () => {
     server.use(
       http.post('/api/v1/feeds', () =>
diff --git a/frontend/src/__tests__/useStudio.test.ts b/frontend/src/__tests__/useStudio.test.ts
index 2364858a..37f2b132 100644
--- a/frontend/src/__tests__/useStudio.test.ts
+++ b/frontend/src/__tests__/useStudio.test.ts
@@ -94,10 +94,7 @@ describe('useStudio', () => {
     expect(handlers.validateCount()).toBe(1);
     expect(handlers.lastValidateAuth()).toBe(`Bearer ${token}`);
 
-    const state = result.current.state;
-    expect(state.phase).toBe('editing');
-    if (state.phase !== 'editing') return;
-    expect(state.validated).toBe(true);
+    expect(result.current.state).toMatchObject({ phase: 'editing', validated: true });
     expect(handlers.previewCount()).toBe(0);
   });
 
@@ -159,11 +156,8 @@ describe('useStudio', () => {
       current.resolve();
       await current.promise;
     });
-    expect(result.current.state.phase).toBe('editing');
-    const state = result.current.state;
-    if (state.phase !== 'editing') return;
-    expect(state.validated).toBe(true);
-    expect(canSaveStudio(state)).toBe(true);
+    expect(result.current.state).toMatchObject({ phase: 'editing', validated: true });
+    expect(canSaveStudio(result.current.state)).toBe(true);
   });
 
   it('fails closed when validate is unauthorized', async () => {
@@ -185,9 +179,11 @@ describe('useStudio', () => {
     );
 
     const { result } = renderHook(() => useStudio({ url: pageUrl, token, validateDelayMs: 0 }));
-    await waitFor(() => expect(result.current.state.phase).toBe('failed'));
-    const state = result.current.state;
-    if (state.phase !== 'failed') return;
-    expect(state.message).toBe('Authentication required');
+    await waitFor(() =>
+      expect(result.current.state).toMatchObject({
+        phase: 'failed',
+        message: 'Authentication required',
+      })
+    );
   });
 });