Add in-app native Gutenberg editor screens

[chubes4]

Goal

Add native Gutenberg authoring screens to extrachill-app using the generic editor package planned for wp-native.

Framework issue:

• Add native Gutenberg editor package chubes4/wp-native#46

Context

extrachill-app/plan.md already lists the authoring vision:

Native Gutenberg Integration inside the app as a primary authoring tool (replacing the web-handoff-only model).

The app is currently Expo/React Native with wp-native-shell auth/navigation and wp-native-client ability execution. It should use the native Gutenberg runtime, not a WebView and not @automattic/isolated-block-editor.

Proposed Screens

Add routes such as:

app/editor/forum-topic.tsx
app/editor/forum-reply.tsx
app/editor/comment.tsx

These screens should configure the generic editor with Extra Chill ability names and route params.

Responsibilities

• Own app navigation, headers, back/save UX, and route params.
• Use wp-native editor primitives instead of direct Gutenberg integration where possible.
• Pass Extra Chill-specific ability names and context into the editor.
• Integrate with existing authenticated app state from wp-native-shell.
• Decide first product target, likely forum reply/topic authoring before broader post/comment editing.

Dependencies

• Generic wp-native editor package: Add native Gutenberg editor package chubes4/wp-native#46
• Server editor abilities in extrachill-api.

Acceptance Criteria

• Authenticated user can open a native editor screen from the app.
• Editor loads existing or draft block content.
• User can edit and save content through abilities.
• Save/error/loading states are visible and mobile-appropriate.
• The app does not rely on browser handoff for the primary authoring flow.

[chubes4]

Related stack issues:

• Generic native editor package: Add native Gutenberg editor package chubes4/wp-native#46
• Server editor abilities: Add editor abilities for native Gutenberg authoring extrachill-api#58
• Auth/session verification: Verify auth/session support for native Gutenberg authoring extrachill-users#51

[chubes4]

Design notes: native Gutenberg editor screens in extrachill-app

Investigation + design only — no code in this comment. Posting per RULES.md "check what already exists before designing new infrastructure": I read the app, plan.md, wp-native-shell/wp-native-client, and the upstream issues before proposing screen shapes.

Edit (correction): Server-side editor abilities live in extrachill-multisite (network-activated, correct home for cross-network abilities), not in extrachill-api. extrachill-api is REST-wrapper-only. The app still calls the abilities via wp-native-client over REST — the transport is unchanged. References throughout this comment have been updated to reflect this. The upstream tracking issue is still extrachill-api#58 until it is moved/relabeled.

1. Scope per plan.md

plan.md lines 9 (vision) and 142–146 (Phase 4) anchor scope:

Authoring vision: Native Gutenberg Integration inside the app as a primary authoring tool (replacing the web-handoff-only model).

Phase 4 — Write Actions (pending)

Ensure API supports app-driven creation flows across ecosystem:

• Create/edit forum topics/replies
• Create/edit comments
• Update artist profiles/links/socials

This issue is the first concrete delivery of that Phase 4 line. The other Phase 4 surfaces (comments, artist updates) come later — the editor screens here lay the route convention and <WPNativeGutenbergEditor> integration pattern they will reuse.

2. Current app shape (what exists, what doesn't)

extrachill-app is at v0.4.0. The full Expo Router tree today is:

app/
├── _layout.tsx            # mounts <WPNativeApp config={config}>...<Slot/>
├── index.tsx              # post-auth onboarding-status redirect
├── login.tsx              # unified login/register (AuthGate intercepts unauth)
├── onboarding.tsx         # KeyboardAvoidingView, calls extrachill/complete-onboarding
└── (drawer)/
    ├── _layout.tsx        # wp-native-shell DrawerContent, headerShown: false
    └── feed.tsx           # placeholder home — section nav coming in Phase 3

Concrete facts that constrain the editor screens:

• No screen renders its own expo-router header today. (drawer)/_layout.tsx sets headerShown: false, and feed.tsx hand-rolls its own 56pt header View with an Avatar/logo. The editor will need to opt into a real header (either Stack-with-header or a hand-rolled view that matches feed.tsx).
• Auth gating is centralised in WPNativeApp.AuthGate (app/_layout.tsx comment block: "AuthGate intercepts unauthenticated users and renders LoginScreen"). New routes inherit gating for free — no per-screen auth checks needed.
• Ability execution surface is useAuth().client.execute<T>(name, input) (see app/onboarding.tsx lines 58–66, 109–116). The client is a WPNativeClient from wp-native-client; its contract is at packages/api-client/src/client.ts — execute() POSTs to wp-abilities/v1/abilities/<name>/run with { input } and unwraps { result }.
• KeyboardAvoidingView with Platform.OS === 'ios' ? 'padding' : 'height' is the established pattern (login.tsx:163, onboarding.tsx:135–137). Editor screens should follow it.
• Loading uses <ActivityIndicator size="large" color={theme.colors.primary}/> centred in a themed container (onboarding.tsx:127, index.tsx:69–73). Errors use the existing <Notice type="error" .../> component (src/components/Notice.tsx, used in login.tsx:193 and onboarding.tsx:166).
• No dirty-state / unsaved-changes prompt exists anywhere in the app today — this is the first screen that needs one. Pattern will need to be invented; see §6.
• No modal presentation has been used yet. Drawer is drawerType: 'front'; everything else is full-screen via <Slot/>. The editor should be full-screen route, not a modal — consistent with login.tsx and onboarding.tsx.
• No app/editor/, app/forum/, app/compose/, or any authoring route exists yet. Greenfield.

3. What this issue actually replaces

Audit of the "web-handoff-only model" the issue says we're replacing: the only handoff code in the repo is useBrowserHandoff() from wp-native-shell (config in extrachill.config.ts:38–42, hosts extrachill.com + *.extrachill.com). It is generic URL handoff, not authoring-specific — it mints a one-time wp-native/auth-browser-handoff token and opens the URL in the browser via Linking.openURL().

So today's "authoring flow" is: tap a forum link → handoff opens browser → user types reply in web Gutenberg. There is no in-app reply UI to replace. This means:

1. We are not removing any existing screens. We are adding the first authoring surface.
2. The forum list/detail screens (issue [APP] Add native bbPress forum integration screens #6, Phase 3) are an upstream prerequisite for navigating to the editor. Until those land, the editor can only be reached via deep link or a temporary debug entry.
3. Browser-handoff stays as the fallback for any URL we don't have a native authoring surface for yet (artist profile edits, shop, comments on the blog).

4. First product target — forum reply

Issue #47 hints "forum reply/topic authoring before broader post/comment editing." Picking forum reply as the first product target.

Rationale:

1. Highest single-flow volume on the platform. Community replies are the most-written content type on extrachill.com. Concrete user pain for handoff today is highest here (mobile users mid-thread bounce to browser, lose context).
2. Smallest editor surface. Replies are body-only — no title, no taxonomy, no featured image, no status/scheduling. Validates the <WPNativeGutenbergEditor> integration end-to-end without dragging in title-bar UI, taxonomy pickers, or publish-state machines that would distract from the editor primitive itself.
3. Cleanest server contract. extrachill/forum.reply.editor.{load,save} (registered in extrachill-multisite, REST-exposed via extrachill-api; tracked in extrachill-api#58) needs only parentId (topic) for create or id for edit. Simpler ability schema = faster end-to-end dogfood.
4. Topic creation is the obvious follow-up. Same <WPNativeGutenbergEditor> host, adds a <TextInput> for title above the editor. Reply de-risks the editor; topic adds one input. Comment editor reuses the same shape on a different ability.

Explicit non-goal for this iteration: topic creation, comment editing, draft auto-save, media upload UX beyond the framework's contract. Each gets its own follow-up.

5. Proposed route tree

app/
└── editor/
    ├── _layout.tsx        # Stack layout, header-aware (or headerShown:false + hand-rolled)
    ├── forum-reply.tsx    # FIRST DELIVERY — body-only editor
    ├── forum-topic.tsx    # follow-up — title + body
    └── comment.tsx        # follow-up — body, comment_post_ID context

Notes on the tree:

• app/editor/ is a sibling of (drawer)/, not nested inside it. The editor is intentionally outside the drawer chrome — it should occupy the full screen and have its own header (Save/Cancel) rather than living under the drawer hamburger. This matches how login.tsx and onboarding.tsx sit outside (drawer)/.
• _layout.tsx here exists to give the editor routes a Stack so the header is real and back-nav is intentional, rather than relying on drawer navigation semantics.
• Each editor screen consumes route params via useLocalSearchParams() (e.g. topicId for new replies, replyId for edits) — matching the pattern documented in wp-native-shell/SectionDetailScreen comments.

6. Screen-level concerns

Header

(drawer)/_layout.tsx sets headerShown: false globally. The editor route group needs its own decision:

• Option A (recommended): Stack with headerShown: true in app/editor/_layout.tsx, configure headerLeft = Cancel, headerRight = Save, headerTitle = "Reply" / "New Topic" / "Edit Comment".
• Option B: hand-rolled header View matching the feed.tsx:28–51 pattern (SafeAreaView + 56pt header View). Use this if we hit RN Stack header customisation limits with KeyboardAvoidingView.

Pick A as default, fall back to B if the keyboard layout fights with Stack's header.

Dirty-state guard on back-nav

No precedent in the app. We need to introduce this. Proposed approach:

1. The editor screen owns a isDirty state (toggled by the editor's onChange).
2. On hardware back / header Cancel / iOS swipe-back, if isDirty, intercept with Alert.alert("Discard changes?", ..., [{text:"Discard", style:"destructive", onPress: ...}, {text:"Keep editing", style:"cancel"}]).
3. Use useNavigation().addListener('beforeRemove', ...) from @react-navigation/native (already a dep) to intercept the navigation event, call e.preventDefault() while the alert is open, then navigation.dispatch(e.data.action) on confirm.

This is a generic-enough pattern that it should live in wp-native-shell as a useDirtyGuard() hook — flagging as coordination note to #46.

Keyboard-aware layout

Reuse the established pattern from login.tsx/onboarding.tsx:

<KeyboardAvoidingView
  style={[styles.container, { backgroundColor: theme.colors.background }]}
  behavior={Platform.OS === 'ios' ? 'padding' : 'height'}
>

The Gutenberg Mobile editor itself manages internal keyboard insets for its toolbars — <WPNativeGutenbergEditor> should not double-pad. We pad the surrounding chrome (header, footer) and let the editor body absorb the keyboard region. Coordination note to wp-native #46: document expected outer KAV behavior so consumers don't over-pad.

Loading / saving / error UI states

Three discrete states per screen, all using existing primitives:

State	UI	Source
Initial load	Centred <ActivityIndicator size="large" color={theme.colors.primary}/> on theme.colors.background	onboarding.tsx:127, index.tsx:69
Load error	<Notice type="error" message={...}/> + Retry button	onboarding.tsx:166
Saving	Header Save button → loading prop on <Button> (already supports it, see login.tsx:228); editor stays interactive but Save disabled	Button component
Save error	<Notice type="error" .../> pinned above editor; editor content preserved; Save re-enabled	onboarding.tsx:166
Save success	Navigate back (router.back() or router.replace(<thread URL>)); no toast in v1 — keep it parallel to onboarding's router.replace('/(drawer)/feed')	onboarding.tsx:117

7. How each screen wires <WPNativeGutenbergEditor>

Assuming the wp-native #46 contract lands as:

<WPNativeGutenbergEditor
  loadAbility="extrachill/forum.reply.editor.load"
  saveAbility="extrachill/forum.reply.editor.save"
  mediaAbility="extrachill/media.upload"
  context={{ replyId, topicId }}
  onDirtyChange={(dirty) => setIsDirty(dirty)}
  onSaveSuccess={(result) => router.back()}
/>

then app/editor/forum-reply.tsx is, in shape:

useLocalSearchParams<{ replyId?: string; topicId?: string }>
  ↓
KeyboardAvoidingView
  ↓
Header (Cancel ←  "Reply"  Save →)
  ↓
<WPNativeGutenbergEditor
    loadAbility="extrachill/forum.reply.editor.load"
    saveAbility="extrachill/forum.reply.editor.save"
    mediaAbility="extrachill/media.upload"
    context={{ replyId: replyId ? Number(replyId) : undefined,
               topicId: topicId ? Number(topicId) : undefined }}
    onDirtyChange={setIsDirty}
    onSaveSuccess={() => router.back()}
    onSaveError={(err) => setError(err.message)}
/>

The extrachill-app screen owns: route params, header chrome, dirty-guard interception, KeyboardAvoidingView. Everything inside the editor (block UI, content state, save lifecycle, media upload UX) is the framework's responsibility.

Ability names are passed in from the screen, not hard-coded in wp-native — matches issue #46's non-goal "Do not put Extra Chill-specific routes or API clients into wp-native."

forum-topic.tsx adds a <TextInput> for title above the editor and passes it as part of context (or as a separate titleAbility prop if #46 settles on that — flag for coordination). comment.tsx is structurally identical to forum-reply.tsx with different ability names and commentPostId instead of topicId.

8. Navigation — how the user reaches the editor

Three entry points, in priority order:

1. From a forum topic detail screen → "Reply" button. This is the primary entry, but it requires forum list/detail screens (issue [APP] Add native bbPress forum integration screens #6, Phase 3) to exist first. Reply button does router.push({ pathname: '/editor/forum-reply', params: { topicId } }).
2. Deep link / browser handoff inbound. When the user is sent to https://community.extrachill.com/...?reply_to=123 from a notification or share-sheet, the app should intercept and route to /editor/forum-reply?topicId=123 instead of bouncing to browser. Coordination with browser-handoff config in extrachill.config.ts:38–42.
3. Drawer "Compose" entry / FAB — explicitly deferred. A floating-action-button or drawer "New Topic" entry only makes sense once the forum section is built and we have a topic-creation flow. Don't add a FAB to feed.tsx (the placeholder home) — that would create a chicken-and-egg compose surface with nowhere meaningful for it to land.

For the first delivery, while forum screens don't exist, ship a temporary debug entry in (drawer)/feed.tsx ("Open editor (debug)" button) that pushes /editor/forum-reply?topicId=<known test topic>. Removed when issue #6's forum detail screen lands.

9. Open questions

1. Offline draft persistence. Should the editor persist a local draft (e.g. via expo-secure-store or AsyncStorage) when the user backgrounds the app or loses connectivity? Strong opinion: yes, eventually, but not in v1 — first ship the round-trip and validate the contract. Local-draft layer can land in a follow-up once we know which level (framework vs. screen) it belongs at. Lean toward framework (wp-native) since every editor consumer wants it.
2. Image picker integration. Gutenberg Mobile has its own MediaPicker. Does <WPNativeGutenbergEditor> pass through to it, or wrap it behind mediaAbility? Need chore: drop @extrachill/api-client dep (M8.1) #46 to clarify. EC's bbPress community currently does not allow inline images in replies — first delivery can ship without media upload entirely and gate the mediaAbility prop as optional.
3. Mention insertion (@username). Community currently has no @-mention block. Out of scope for v1. If we want it, it's a Gutenberg block — belongs in extrachill-content-blocks or a new extrachill-community-blocks plugin, not in the app or wp-native.
4. Link insertion for unauthenticated *.extrachill.link URLs. The browser-handoff config excludes *.extrachill.link — this is unrelated to the editor and stays as-is.
5. Save success destination. router.back() returns to the forum thread, but the thread's reply list won't auto-refresh. Forum detail screen (issue [APP] Add native bbPress forum integration screens #6) needs a refresh-on-focus pattern. For first delivery (debug entry from feed), router.back() returns to feed which is fine.
6. Auth/session lifetime during long edits. Access token TTL is 15min (plan.md:46). A user composing a long reply can have the token expire mid-edit. wp-native-shell's AuthFetchTransport auto-refreshes on 401, so save should self-heal — but worth explicit test. Tracking on extrachill-users fix: align native font registration #51.

10. Coordination notes back upstream

→ wp-native #46 (editor package)

• Confirm <WPNativeGutenbergEditor> (or <WPNativeEditorScreen>) public API. We are designing screens assuming the inner primitive (consumer owns header/back/save chrome). If chore: drop @extrachill/api-client dep (M8.1) #46 lands the screen-level wrapper instead, our routes get thinner — the route file becomes <WPNativeEditorScreen title="Reply" loadAbility="..." saveAbility="..." mediaAbility="..."/> and a tiny wrapper for KAV/dirty guard.
• Need onDirtyChange(isDirty) callback exposed for the dirty-guard pattern. Or, alternatively, expose an imperative editorRef.isDirty() getter — either works, but a callback is more React-idiomatic.
• Document expected outer KeyboardAvoidingView behavior so consumers don't double-pad keyboard insets.
• Consider extracting a generic useDirtyGuard(navigation, isDirty) hook into wp-native-shell — it's not editor-specific (any form would want it).
• Clarify media-upload contract: is mediaAbility optional? If undefined, does the editor hide the media-insert toolbar button entirely?
• Clarify save-result shape passed to onSaveSuccess — at minimum { id, status, permalink? } per the proposed save result in extrachill-api#58.

→ extrachill-multisite (server abilities, tracked in extrachill-api#58)

Ownership note: abilities register in extrachill-multisite (network-activated). extrachill-api is the REST wrapper only. The upstream issue is still filed at extrachill-api#58 until it is moved/relabeled to point at extrachill-multisite. The app consumes them unchanged via wp-native-client over REST.

• Confirm extrachill/forum.reply.editor.{load,save} are the canonical ability names. The screen hard-codes them.
• For new replies (no id yet), the load ability needs to accept parentId (topic) and return an empty-but-permissioned shell: { id: undefined, type: 'forum_reply', content: '', context: { parentId }, permissions: { canSave: true, canUploadMedia: ... } }. Confirm this is the intended new-vs-edit dispatch shape, or whether new compose skips load entirely and the screen seeds empty content directly.
• permissions.canSave: false should map to a read-only editor + hidden Save button. Confirm the framework reads permissions from the load result and propagates UI state.
• media.upload ability scope: replies in extrachill-community currently do not support inline images. Confirm whether the ability is registered for forum replies at all in v1 — if not, the screen passes mediaAbility={undefined} and the toolbar button is hidden.
• Multisite routing: forum replies live on community.extrachill.com (Blog ID 2). The ability must switch_to_blog(ec_get_blog_id('community')) server-side per the API Gateway Rule (plan.md:26–34). This is exactly why the abilities belong in extrachill-multisite rather than extrachill-api — cross-network routing is a network-activation concern, not a REST-wrapper concern. Flag in #58.

→ extrachill-app #6 (forum list/detail screens)

• The "Reply" button entry point for the editor is your responsibility. Coordinate so that router.push({ pathname: '/editor/forum-reply', params: { topicId } }) is the contract.
• Refresh-on-focus pattern for the topic detail screen when returning from the editor — needs useFocusEffect to re-fetch the reply list. Out of scope here, but flag it on [APP] Add native bbPress forum integration screens #6.

→ extrachill-users #51 (auth/session verification)

• Long-running edit sessions must survive a token expiry without losing the user's draft. Verify the AuthFetchTransport refresh-on-401 path actually fires on POST /wp-abilities/v1/abilities/<name>/run (not just GET).

---

cc <@532385681268408341> — design notes complete and ready for review.

[chubes4]

Parked. Per chubes4/wp-native#48 — native Gutenberg editor work is paused while @wordpress/react-native-editor is broken on React 19. App stays on browser-handoff authoring (already wired via wp-native-shell's useBrowserHandoff()) until upstream catches up.

Design notes on this issue remain valid for when work resumes — route tree, dirty-state guard pattern, KeyboardAvoidingView usage, and ability-name conventions all carry forward. The first product target (forum reply) and the rationale for it are also documented above and worth preserving.

Keeping open as a parked tracking issue.