A calm place to write long-form, and publish it to the open social web.
skypress.blog/
Add the writing-first flow design spec + implementation plan
author
Jeremy Herve
date
(Jun 17, 2026, 1:14 PM +0200)
commit
25a2b38a
25a2b38a4f998e3a98a0a4ed2f55ee4bed0e0059
parent
438afcd0
438afcd0b5955f9fdac960b7d2ed6facc75ff302
+2382
+2229
docs/superpowers/plans/2026-06-17-writing-first-flow.md
+2229
docs/superpowers/plans/2026-06-17-writing-first-flow.md
···
1
+
# Writing-first Flow Implementation Plan
2
+
3
+
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
4
+
5
+
**Goal:** Add a parallel `/write` experience where the writer lands directly in the editor, writes immediately with no login gate, and only meets authentication + publication selection at publish time — with images held locally and uploaded at publish.
6
+
7
+
**Architecture:** A new client-only `WriteStudio` island at `/write` wraps the existing `AuthProvider` but renders the editor for *every* auth status. Images insert as `data:` URL previews and are never uploaded during editing. The full draft (title, lede, blocks, cover) survives the OAuth full-page redirect via a draft store that keeps light metadata + token-skeletoned blocks in `localStorage` and the heavy image bytes in IndexedDB. Clicking **Publish** persists the draft, stamps a `publishIntent`, and (if signed out) redirects to OAuth; on return the flow auto-resumes, branches on publication count (one → confirm / many → pick / zero → inline create), uploads held images, then reuses the existing `publish()` to write the document + Bluesky post.
8
+
9
+
**Tech Stack:** Astro (file-router islands), React 18, `@automattic/isolated-block-editor`, `@atproto/api`, TypeScript, Vitest (jsdom; component tests via raw `react-dom/client` + `act`, **no** testing-library).
10
+
11
+
## Global Constraints
12
+
13
+
- **React 18 only** — never introduce React 19. (Decision 0001)
14
+
- **`@wordpress/*` is version-pinned via `overrides`** — do not bump `isolated-block-editor` here. (Decision 0003)
15
+
- **Reading pages must never import `@wordpress/*`.** All new editor code is browser-only and belongs in the `client:only` island or in tests. (Decision 0003)
16
+
- **Colocated tests under `src/pages/` MUST be underscore-prefixed** (e.g. `_write.meta.test.ts`) or Astro's router will execute them during prerender and 500 the build. (AGENTS.md §8)
17
+
- **Don't surprise users:** publishing also creates a public Bluesky post — every confirm step must say so. (Brief §10)
18
+
- **No remote account creation.** OAuth is sign-in only; the signed-out panel offers a *link out* to Bluesky signup, never an inline create-account flow. (Brief guardrail; design Q2)
19
+
- **OAuth is a browser public client**; the `redirect_uri` is the current pathname, so a sign-in from `/write` returns to `/write` with no new config. (Decision 0004)
20
+
- New PHP/TS files: this is a TS/Astro repo — match existing tab indentation and the `import type` style used throughout `src/`.
21
+
- License header convention: follow the surrounding files (none carry per-file license headers today — do not add any).
22
+
23
+
## File Structure
24
+
25
+
**New library modules (browser, unit-tested):**
26
+
- `src/lib/write/deferred-media.ts` — a `mediaUpload` handler that previews via `data:` URL and uploads nothing.
27
+
- `src/lib/write/held-assets.ts` — pure helpers: detect `data:` URLs, split/merge image `data:` URLs out of a block tree (+ cover) into a token→bytes map, and rebuild a `Blob` from a `data:` URL.
28
+
- `src/lib/write/asset-store.ts` — `AssetStore` interface + an IndexedDB implementation + an in-memory implementation (for SSR-absent envs and tests).
29
+
- `src/lib/write/draft-store.ts` — orchestrates `localStorage` (metadata + token-skeleton blocks + the publish-intent flag) and an injected `AssetStore` (image bytes) into one save/load/clear API.
30
+
- `src/lib/write/upload-held.ts` — at publish: upload every held `data:` image (+ cover) to the PDS and return a publish-ready block tree + cover ref.
31
+
32
+
**New components (browser island):**
33
+
- `src/components/SignInPanel.tsx` — signed-out handle entry; one variant carries publish intent, one doesn't; includes the "Need an account? →" link out.
34
+
- `src/components/AccountPill.tsx` — signed-in avatar/handle pill with a small menu (Manage publications, Profile, Sign out).
35
+
- `src/components/WritePublishFlow.tsx` — the publish stepper (branch → confirm/pick/create → upload → publish).
36
+
- `src/components/WriteStudio.tsx` — the island: editor for all auth states, persistence, redirect, resume.
37
+
38
+
**New route + styles:**
39
+
- `src/pages/write.astro` — mounts `WriteStudio` (`client:only`).
40
+
- `src/pages/_write.meta.test.ts` — route metadata test (underscore-prefixed).
41
+
- `src/styles/write-chrome.css` — corner pill / sign-in panel / publish-flow styling.
42
+
43
+
**New decision doc:**
44
+
- `docs/decisions/0020-writing-first-deferred-publish.md`
45
+
46
+
**Untouched:** `src/pages/index.astro`, `src/pages/editor.astro`, `src/components/Studio.tsx`, `src/components/PublishPanel.tsx`, `src/components/Dashboard.tsx`, `src/lib/media/mediaUpload.ts`, `src/components/SkyEditor.tsx`.
47
+
48
+
**Reused unchanged (imported):** `AuthProvider`, `useAuth`, `oauth.ts`, `SkyEditor`, `PublicationForm`, `publisher.ts` (`publish`, `Identity`), `publications.ts` (`listPublications`, `Publication`), `records.ts` (`normalizeBlocks`), `blob.ts` (`attachBlobRefs`, `buildGetBlobUrl`, `BlobRefJson`, `BlobUpload`), `profile.ts` (`authorPath`, `displayNameFor`), `PublishPanel.tsx`'s exported `computePostPreview`, `AppBar`, `PublishedPill`, `CoverImagePicker`.
49
+
50
+
---
51
+
52
+
### Task 1: Deferred media handler
53
+
54
+
A Gutenberg `mediaUpload` handler that, unlike the eager one, never touches the PDS: it reads each file into a `data:` URL and hands it back for inline preview. The actual upload is deferred to publish.
55
+
56
+
**Files:**
57
+
- Create: `src/lib/write/deferred-media.ts`
58
+
- Test: `src/lib/write/deferred-media.test.ts`
59
+
60
+
**Interfaces:**
61
+
- Consumes: `MediaUploadHandler`, `MediaUploadArgs` shape from `src/lib/media/mediaUpload.ts` (the handler is `(args) => Promise<void>` where `args` has `filesList`, `onFileChange`, `onError?`, `maxUploadFileSize?`).
62
+
- Produces: `export function createDeferredMediaUpload(): MediaUploadHandler`
63
+
64
+
- [ ] **Step 1: Write the failing test**
65
+
66
+
```ts
67
+
// src/lib/write/deferred-media.test.ts
68
+
import { describe, it, expect, vi } from 'vitest';
69
+
import { createDeferredMediaUpload } from './deferred-media';
70
+
71
+
describe( 'createDeferredMediaUpload', () => {
72
+
it( 'previews each file as a data: URL and uploads nothing', async () => {
73
+
const handler = createDeferredMediaUpload();
74
+
const file = new File( [ 'x' ], 'cat.png', { type: 'image/png' } );
75
+
const onFileChange = vi.fn();
76
+
77
+
await handler( { filesList: [ file ], onFileChange } );
78
+
79
+
expect( onFileChange ).toHaveBeenCalledTimes( 1 );
80
+
const [ media ] = onFileChange.mock.calls[ 0 ][ 0 ];
81
+
expect( media.url.startsWith( 'data:image/png;base64,' ) ).toBe( true );
82
+
expect( media.url.startsWith( 'blob:' ) ).toBe( false );
83
+
expect( 'id' in media ).toBe( false );
84
+
} );
85
+
86
+
it( 'rejects oversize files via onError without previewing them', async () => {
87
+
const handler = createDeferredMediaUpload();
88
+
const big = new File( [ 'x' ], 'big.png', { type: 'image/png' } );
89
+
Object.defineProperty( big, 'size', { value: 5_000_000 } );
90
+
const onFileChange = vi.fn();
91
+
const onError = vi.fn();
92
+
93
+
await handler( {
94
+
filesList: [ big ],
95
+
onFileChange,
96
+
onError,
97
+
maxUploadFileSize: 1_000_000,
98
+
} );
99
+
100
+
expect( onFileChange ).not.toHaveBeenCalled();
101
+
expect( onError ).toHaveBeenCalledTimes( 1 );
102
+
expect( onError.mock.calls[ 0 ][ 0 ] ).toBeInstanceOf( Error );
103
+
} );
104
+
} );
105
+
```
106
+
107
+
- [ ] **Step 2: Run test to verify it fails**
108
+
109
+
Run: `npx vitest run src/lib/write/deferred-media.test.ts`
110
+
Expected: FAIL — cannot resolve `./deferred-media`.
111
+
112
+
- [ ] **Step 3: Write the implementation**
113
+
114
+
```ts
115
+
// src/lib/write/deferred-media.ts
116
+
import type { MediaUploadHandler } from '../media/mediaUpload';
117
+
118
+
/** Read a file into a `data:` URL (base64) for inline preview. */
119
+
function readAsDataUrl( file: File ): Promise< string > {
120
+
return new Promise( ( resolve, reject ) => {
121
+
const reader = new FileReader();
122
+
reader.onload = () => resolve( reader.result as string );
123
+
reader.onerror = () =>
124
+
reject( reader.error ?? new Error( `Could not read "${ file.name }".` ) );
125
+
reader.readAsDataURL( file );
126
+
} );
127
+
}
128
+
129
+
/**
130
+
* A Gutenberg `mediaUpload` handler for the writing-first flow (design 2026-06-17): it
131
+
* previews each file from a `data:` URL and uploads NOTHING to a PDS. The real upload is
132
+
* deferred to publish (see `upload-held.ts`), so the editor works while signed out.
133
+
*
134
+
* Like the eager handler it must preview from a `data:` URL, never a `blob:` URL — the Image
135
+
* block treats a `blob:` URL as still-uploading and re-runs its upload hook forever.
136
+
*/
137
+
export function createDeferredMediaUpload(): MediaUploadHandler {
138
+
return async function deferredMediaUpload( {
139
+
filesList,
140
+
onFileChange,
141
+
onError,
142
+
maxUploadFileSize,
143
+
} ): Promise< void > {
144
+
for ( const file of Array.from( filesList ) ) {
145
+
try {
146
+
if ( maxUploadFileSize && file.size > maxUploadFileSize ) {
147
+
const mb = Math.round( maxUploadFileSize / 1024 / 1024 );
148
+
throw new Error( `"${ file.name }" exceeds the ${ mb }MB limit.` );
149
+
}
150
+
const previewUrl = await readAsDataUrl( file );
151
+
// No `id`: PDS blobs aren't WP attachments (mirrors the eager handler).
152
+
onFileChange( [ { url: previewUrl, alt: '' } ] );
153
+
} catch ( error ) {
154
+
onError?.( error instanceof Error ? error : new Error( String( error ) ) );
155
+
}
156
+
}
157
+
};
158
+
}
159
+
```
160
+
161
+
- [ ] **Step 4: Run test to verify it passes**
162
+
163
+
Run: `npx vitest run src/lib/write/deferred-media.test.ts`
164
+
Expected: PASS (both tests).
165
+
166
+
- [ ] **Step 5: Commit**
167
+
168
+
```bash
169
+
git add src/lib/write/deferred-media.ts src/lib/write/deferred-media.test.ts
170
+
git commit --no-gpg-sign -m "Add deferred media handler for writing-first editor"
171
+
```
172
+
173
+
---
174
+
175
+
### Task 2: Held-asset split/merge + data-URL helpers (pure)
176
+
177
+
Pure logic to: recognise `data:` URLs, rebuild a `Blob` from one, and split image `data:` URLs (in `core/image` blocks at any depth, plus the cover) out of a tree into a small token-skeleton + a `token → dataUrl` map (and merge them back). This is what lets large image bytes live in IndexedDB while the block skeleton stays small in `localStorage`.
178
+
179
+
**Files:**
180
+
- Create: `src/lib/write/held-assets.ts`
181
+
- Test: `src/lib/write/held-assets.test.ts`
182
+
183
+
**Interfaces:**
184
+
- Consumes: `BlockNode` from `src/lib/blocks/render.ts` (`{ name: string; attributes?: Record<string, unknown>; innerBlocks?: BlockNode[] }`).
185
+
- Produces:
186
+
- `export function isDataUrl( value: unknown ): value is string`
187
+
- `export function dataUrlToBlob( dataUrl: string ): Blob`
188
+
- `export interface AssetSkeleton { blocks: BlockNode[]; cover: string | null }`
189
+
- `export function splitAssets( blocks: BlockNode[], coverDataUrl: string | null ): { skeleton: AssetSkeleton; assets: Record< string, string > }`
190
+
- `export function mergeAssets( skeleton: AssetSkeleton, assets: Record< string, string > ): { blocks: BlockNode[]; coverDataUrl: string | null }`
191
+
- Token format: body images `a0`, `a1`, … (allocation order is depth-first); cover token is the literal `cover`.
192
+
193
+
- [ ] **Step 1: Write the failing test**
194
+
195
+
```ts
196
+
// src/lib/write/held-assets.test.ts
197
+
import { describe, it, expect } from 'vitest';
198
+
import {
199
+
isDataUrl,
200
+
dataUrlToBlob,
201
+
splitAssets,
202
+
mergeAssets,
203
+
} from './held-assets';
204
+
import type { BlockNode } from '../blocks/render';
205
+
206
+
const DATA_A = 'data:image/png;base64,QUFB'; // "AAA"
207
+
const DATA_B = 'data:image/jpeg;base64,QkJC'; // "BBB"
208
+
209
+
function tree(): BlockNode[] {
210
+
return [
211
+
{ name: 'core/paragraph', attributes: { content: 'hi' }, innerBlocks: [] },
212
+
{ name: 'core/image', attributes: { url: DATA_A }, innerBlocks: [] },
213
+
{
214
+
name: 'core/columns',
215
+
attributes: {},
216
+
innerBlocks: [
217
+
{ name: 'core/image', attributes: { url: DATA_B }, innerBlocks: [] },
218
+
{ name: 'core/image', attributes: { url: 'https://ext/img.png' }, innerBlocks: [] },
219
+
],
220
+
},
221
+
];
222
+
}
223
+
224
+
describe( 'isDataUrl', () => {
225
+
it( 'matches data: URLs only', () => {
226
+
expect( isDataUrl( DATA_A ) ).toBe( true );
227
+
expect( isDataUrl( 'https://x/y.png' ) ).toBe( true === false ); // not a data URL
228
+
expect( isDataUrl( undefined ) ).toBe( false );
229
+
} );
230
+
} );
231
+
232
+
describe( 'dataUrlToBlob', () => {
233
+
it( 'reconstructs bytes + mime from a data: URL', async () => {
234
+
const blob = dataUrlToBlob( DATA_A );
235
+
expect( blob.type ).toBe( 'image/png' );
236
+
expect( await blob.text() ).toBe( 'AAA' );
237
+
} );
238
+
} );
239
+
240
+
describe( 'splitAssets / mergeAssets', () => {
241
+
it( 'extracts every data: image URL (depth-first) + cover into tokens and round-trips', () => {
242
+
const { skeleton, assets } = splitAssets( tree(), DATA_A );
243
+
244
+
// Body data URLs replaced by tokens; external + non-image untouched.
245
+
expect( skeleton.blocks[ 1 ].attributes!.url ).toBe( 'a0' );
246
+
expect( skeleton.blocks[ 2 ].innerBlocks![ 0 ].attributes!.url ).toBe( 'a1' );
247
+
expect( skeleton.blocks[ 2 ].innerBlocks![ 1 ].attributes!.url ).toBe( 'https://ext/img.png' );
248
+
expect( skeleton.cover ).toBe( 'cover' );
249
+
expect( assets ).toEqual( { a0: DATA_A, a1: DATA_B, cover: DATA_A } );
250
+
251
+
const merged = mergeAssets( skeleton, assets );
252
+
expect( merged.blocks ).toEqual( tree() );
253
+
expect( merged.coverDataUrl ).toBe( DATA_A );
254
+
} );
255
+
256
+
it( 'leaves a null cover null and a tree with no data URLs unchanged', () => {
257
+
const plain: BlockNode[] = [
258
+
{ name: 'core/image', attributes: { url: 'https://ext/x.png' }, innerBlocks: [] },
259
+
];
260
+
const { skeleton, assets } = splitAssets( plain, null );
261
+
expect( assets ).toEqual( {} );
262
+
expect( skeleton.cover ).toBe( null );
263
+
expect( mergeAssets( skeleton, assets ) ).toEqual( { blocks: plain, coverDataUrl: null } );
264
+
} );
265
+
} );
266
+
```
267
+
268
+
> Note: the `isDataUrl( 'https://x/y.png' )` assertion above is written `toBe( true === false )` (i.e. `false`) deliberately so the test reads as "an https URL is NOT a data URL". If you prefer, replace with `.toBe( false )`.
269
+
270
+
- [ ] **Step 2: Run test to verify it fails**
271
+
272
+
Run: `npx vitest run src/lib/write/held-assets.test.ts`
273
+
Expected: FAIL — cannot resolve `./held-assets`.
274
+
275
+
- [ ] **Step 3: Write the implementation**
276
+
277
+
```ts
278
+
// src/lib/write/held-assets.ts
279
+
import type { BlockNode } from '../blocks/render';
280
+
281
+
/** Block names whose `url` attribute may hold a held (data:) image. Mirrors blob.ts. */
282
+
const IMAGE_BLOCKS = new Set( [ 'core/image' ] );
283
+
284
+
/** True when `value` is a `data:` URL string. */
285
+
export function isDataUrl( value: unknown ): value is string {
286
+
return typeof value === 'string' && value.startsWith( 'data:' );
287
+
}
288
+
289
+
/** Rebuild a `Blob` (bytes + mime type) from a base64 `data:` URL. */
290
+
export function dataUrlToBlob( dataUrl: string ): Blob {
291
+
const comma = dataUrl.indexOf( ',' );
292
+
const header = dataUrl.slice( 5, comma ); // after "data:"
293
+
const mimeType = header.split( ';' )[ 0 ] || 'application/octet-stream';
294
+
const base64 = dataUrl.slice( comma + 1 );
295
+
const binary = atob( base64 );
296
+
const bytes = new Uint8Array( binary.length );
297
+
for ( let i = 0; i < binary.length; i++ ) {
298
+
bytes[ i ] = binary.charCodeAt( i );
299
+
}
300
+
return new Blob( [ bytes ], { type: mimeType } );
301
+
}
302
+
303
+
export interface AssetSkeleton {
304
+
blocks: BlockNode[];
305
+
/** `'cover'` when a held cover exists, else `null`. */
306
+
cover: string | null;
307
+
}
308
+
309
+
/**
310
+
* Replace every held (`data:`) image URL in the tree — and the cover — with a short token,
311
+
* returning the lightweight skeleton plus a `token → dataUrl` map. Body tokens are `a0`,
312
+
* `a1`, … allocated depth-first; the cover token is the literal `'cover'`. External image
313
+
* URLs and non-image blocks are left untouched. Pure; returns new objects.
314
+
*/
315
+
export function splitAssets(
316
+
blocks: BlockNode[],
317
+
coverDataUrl: string | null
318
+
): { skeleton: AssetSkeleton; assets: Record< string, string > } {
319
+
const assets: Record< string, string > = {};
320
+
let n = 0;
321
+
322
+
const walk = ( nodes: BlockNode[] ): BlockNode[] =>
323
+
nodes.map( ( node ) => {
324
+
const url = node.attributes?.url;
325
+
const held = IMAGE_BLOCKS.has( node.name ) && isDataUrl( url );
326
+
let attributes = node.attributes ? { ...node.attributes } : {};
327
+
if ( held ) {
328
+
const token = `a${ n++ }`;
329
+
assets[ token ] = url as string;
330
+
attributes = { ...attributes, url: token };
331
+
}
332
+
return {
333
+
name: node.name,
334
+
attributes,
335
+
innerBlocks: walk( node.innerBlocks ?? [] ),
336
+
};
337
+
} );
338
+
339
+
const skeletonBlocks = walk( blocks );
340
+
let cover: string | null = null;
341
+
if ( isDataUrl( coverDataUrl ) ) {
342
+
assets.cover = coverDataUrl;
343
+
cover = 'cover';
344
+
}
345
+
return { skeleton: { blocks: skeletonBlocks, cover }, assets };
346
+
}
347
+
348
+
/** Inverse of `splitAssets`: swap each token back to its `data:` URL. Pure. */
349
+
export function mergeAssets(
350
+
skeleton: AssetSkeleton,
351
+
assets: Record< string, string >
352
+
): { blocks: BlockNode[]; coverDataUrl: string | null } {
353
+
const walk = ( nodes: BlockNode[] ): BlockNode[] =>
354
+
nodes.map( ( node ) => {
355
+
const url = node.attributes?.url;
356
+
const restore =
357
+
IMAGE_BLOCKS.has( node.name ) && typeof url === 'string' && url in assets;
358
+
return {
359
+
name: node.name,
360
+
attributes: restore
361
+
? { ...node.attributes, url: assets[ url as string ] }
362
+
: { ...( node.attributes ?? {} ) },
363
+
innerBlocks: walk( node.innerBlocks ?? [] ),
364
+
};
365
+
} );
366
+
367
+
return {
368
+
blocks: walk( skeleton.blocks ),
369
+
coverDataUrl: skeleton.cover ? assets[ skeleton.cover ] ?? null : null,
370
+
};
371
+
}
372
+
```
373
+
374
+
- [ ] **Step 4: Run test to verify it passes**
375
+
376
+
Run: `npx vitest run src/lib/write/held-assets.test.ts`
377
+
Expected: PASS.
378
+
379
+
- [ ] **Step 5: Commit**
380
+
381
+
```bash
382
+
git add src/lib/write/held-assets.ts src/lib/write/held-assets.test.ts
383
+
git commit --no-gpg-sign -m "Add pure held-asset split/merge + data-URL helpers"
384
+
```
385
+
386
+
---
387
+
388
+
### Task 3: Asset store (IndexedDB + in-memory)
389
+
390
+
A tiny key→value store for held image bytes. The interface is what `draft-store` depends on; the in-memory implementation is what tests inject (jsdom has no IndexedDB) and the SSR/quota-failure fallback.
391
+
392
+
**Files:**
393
+
- Create: `src/lib/write/asset-store.ts`
394
+
- Test: `src/lib/write/asset-store.test.ts`
395
+
396
+
**Interfaces:**
397
+
- Produces:
398
+
- `export interface AssetStore { put( assets: Record< string, string > ): Promise< void >; getAll(): Promise< Record< string, string > >; clear(): Promise< void >; }`
399
+
- `export function createMemoryAssetStore(): AssetStore`
400
+
- `export function createIndexedDbAssetStore( dbName?: string, storeName?: string ): AssetStore`
401
+
402
+
- [ ] **Step 1: Write the failing test** (covers the in-memory store; the IndexedDB impl is exercised via `draft-store` integration + manual smoke)
403
+
404
+
```ts
405
+
// src/lib/write/asset-store.test.ts
406
+
import { describe, it, expect } from 'vitest';
407
+
import { createMemoryAssetStore } from './asset-store';
408
+
409
+
describe( 'createMemoryAssetStore', () => {
410
+
it( 'puts, merges, reads all, and clears', async () => {
411
+
const store = createMemoryAssetStore();
412
+
await store.put( { a0: 'data:1' } );
413
+
await store.put( { a1: 'data:2' } );
414
+
expect( await store.getAll() ).toEqual( { a0: 'data:1', a1: 'data:2' } );
415
+
await store.clear();
416
+
expect( await store.getAll() ).toEqual( {} );
417
+
} );
418
+
419
+
it( 'replaces a key on re-put', async () => {
420
+
const store = createMemoryAssetStore();
421
+
await store.put( { a0: 'data:1' } );
422
+
await store.put( { a0: 'data:CHANGED' } );
423
+
expect( await store.getAll() ).toEqual( { a0: 'data:CHANGED' } );
424
+
} );
425
+
} );
426
+
```
427
+
428
+
- [ ] **Step 2: Run test to verify it fails**
429
+
430
+
Run: `npx vitest run src/lib/write/asset-store.test.ts`
431
+
Expected: FAIL — cannot resolve `./asset-store`.
432
+
433
+
- [ ] **Step 3: Write the implementation**
434
+
435
+
```ts
436
+
// src/lib/write/asset-store.ts
437
+
438
+
/**
439
+
* A small async key→value store for held image bytes (data: URLs) in the writing-first flow.
440
+
* Held bytes can be large, so they live here (IndexedDB) rather than in localStorage with the
441
+
* draft metadata. `put` MERGES (does not replace the whole store) so adding an image keeps the
442
+
* earlier ones; `clear` empties everything (called after a successful publish or a discard).
443
+
*/
444
+
export interface AssetStore {
445
+
put( assets: Record< string, string > ): Promise< void >;
446
+
getAll(): Promise< Record< string, string > >;
447
+
clear(): Promise< void >;
448
+
}
449
+
450
+
/** In-memory store: the test/SSR/quota-failure fallback. Survives nothing past a reload. */
451
+
export function createMemoryAssetStore(): AssetStore {
452
+
let map: Record< string, string > = {};
453
+
return {
454
+
async put( assets ) {
455
+
map = { ...map, ...assets };
456
+
},
457
+
async getAll() {
458
+
return { ...map };
459
+
},
460
+
async clear() {
461
+
map = {};
462
+
},
463
+
};
464
+
}
465
+
466
+
const DEFAULT_DB = 'skypress-write';
467
+
const DEFAULT_STORE = 'assets';
468
+
469
+
function openDb( dbName: string, storeName: string ): Promise< IDBDatabase > {
470
+
return new Promise( ( resolve, reject ) => {
471
+
const req = indexedDB.open( dbName, 1 );
472
+
req.onupgradeneeded = () => {
473
+
if ( ! req.result.objectStoreNames.contains( storeName ) ) {
474
+
req.result.createObjectStore( storeName );
475
+
}
476
+
};
477
+
req.onsuccess = () => resolve( req.result );
478
+
req.onerror = () => reject( req.error ?? new Error( 'IndexedDB open failed' ) );
479
+
} );
480
+
}
481
+
482
+
/**
483
+
* IndexedDB-backed asset store. Each token is one record keyed by the token string. Falls back
484
+
* to an in-memory store when IndexedDB is unavailable (e.g. SSR/tests) so callers never crash.
485
+
*/
486
+
export function createIndexedDbAssetStore(
487
+
dbName: string = DEFAULT_DB,
488
+
storeName: string = DEFAULT_STORE
489
+
): AssetStore {
490
+
if ( typeof indexedDB === 'undefined' ) {
491
+
return createMemoryAssetStore();
492
+
}
493
+
494
+
const tx = async < T >(
495
+
mode: IDBTransactionMode,
496
+
run: ( store: IDBObjectStore ) => IDBRequest | void,
497
+
read?: ( store: IDBObjectStore ) => IDBRequest< T >
498
+
): Promise< T | void > => {
499
+
const db = await openDb( dbName, storeName );
500
+
return new Promise< T | void >( ( resolve, reject ) => {
501
+
const transaction = db.transaction( storeName, mode );
502
+
const store = transaction.objectStore( storeName );
503
+
let readReq: IDBRequest< T > | undefined;
504
+
if ( read ) {
505
+
readReq = read( store );
506
+
} else {
507
+
run( store );
508
+
}
509
+
transaction.oncomplete = () => {
510
+
db.close();
511
+
resolve( readReq ? readReq.result : undefined );
512
+
};
513
+
transaction.onerror = () => {
514
+
db.close();
515
+
reject( transaction.error ?? new Error( 'IndexedDB transaction failed' ) );
516
+
};
517
+
} );
518
+
};
519
+
520
+
return {
521
+
async put( assets ) {
522
+
await tx( 'readwrite', ( store ) => {
523
+
for ( const [ key, value ] of Object.entries( assets ) ) {
524
+
store.put( value, key );
525
+
}
526
+
} );
527
+
},
528
+
async getAll() {
529
+
const db = await openDb( dbName, storeName );
530
+
return new Promise< Record< string, string > >( ( resolve, reject ) => {
531
+
const transaction = db.transaction( storeName, 'readonly' );
532
+
const store = transaction.objectStore( storeName );
533
+
const keysReq = store.getAllKeys();
534
+
const valsReq = store.getAll();
535
+
transaction.oncomplete = () => {
536
+
db.close();
537
+
const out: Record< string, string > = {};
538
+
( keysReq.result as IDBValidKey[] ).forEach( ( k, i ) => {
539
+
out[ String( k ) ] = valsReq.result[ i ] as string;
540
+
} );
541
+
resolve( out );
542
+
};
543
+
transaction.onerror = () => {
544
+
db.close();
545
+
reject( transaction.error ?? new Error( 'IndexedDB read failed' ) );
546
+
};
547
+
} );
548
+
},
549
+
async clear() {
550
+
await tx( 'readwrite', ( store ) => store.clear() );
551
+
},
552
+
};
553
+
}
554
+
```
555
+
556
+
- [ ] **Step 4: Run test to verify it passes**
557
+
558
+
Run: `npx vitest run src/lib/write/asset-store.test.ts`
559
+
Expected: PASS.
560
+
561
+
- [ ] **Step 5: Commit**
562
+
563
+
```bash
564
+
git add src/lib/write/asset-store.ts src/lib/write/asset-store.test.ts
565
+
git commit --no-gpg-sign -m "Add asset store (IndexedDB + in-memory) for held image bytes"
566
+
```
567
+
568
+
---
569
+
570
+
### Task 4: Draft store
571
+
572
+
Combine `localStorage` (title, lede, token-skeleton blocks, cover token, `publishIntent`) and an injected `AssetStore` (image bytes) into one save/load/clear API. This is what survives the OAuth redirect.
573
+
574
+
**Files:**
575
+
- Create: `src/lib/write/draft-store.ts`
576
+
- Test: `src/lib/write/draft-store.test.ts`
577
+
578
+
**Interfaces:**
579
+
- Consumes: `splitAssets`, `mergeAssets`, `AssetSkeleton` from `./held-assets`; `AssetStore`, `createMemoryAssetStore`, `createIndexedDbAssetStore` from `./asset-store`; `BlockNode`.
580
+
- Produces:
581
+
- `export interface WriteDraft { title: string; lede: string; blocks: BlockNode[]; coverDataUrl: string | null }`
582
+
- `export interface DraftStore { save( draft: WriteDraft ): Promise< void >; load(): Promise< WriteDraft | null >; clear(): Promise< void >; setPublishIntent(): void; consumePublishIntent(): boolean }`
583
+
- `export function createDraftStore( opts?: { assets?: AssetStore; storage?: Storage } ): DraftStore`
584
+
- localStorage keys: meta → `skypress:write:draft`; intent → `skypress:write:publish-intent`.
585
+
586
+
- [ ] **Step 1: Write the failing test**
587
+
588
+
```ts
589
+
// src/lib/write/draft-store.test.ts
590
+
import { describe, it, expect, beforeEach } from 'vitest';
591
+
import { createDraftStore, type WriteDraft } from './draft-store';
592
+
import { createMemoryAssetStore } from './asset-store';
593
+
import type { BlockNode } from '../blocks/render';
594
+
595
+
const DATA = 'data:image/png;base64,QUFB';
596
+
597
+
function draft(): WriteDraft {
598
+
return {
599
+
title: 'Hello',
600
+
lede: 'A lede',
601
+
blocks: [
602
+
{ name: 'core/paragraph', attributes: { content: 'hi' }, innerBlocks: [] },
603
+
{ name: 'core/image', attributes: { url: DATA }, innerBlocks: [] },
604
+
] as BlockNode[],
605
+
coverDataUrl: DATA,
606
+
};
607
+
}
608
+
609
+
beforeEach( () => window.localStorage.clear() );
610
+
611
+
function newStore() {
612
+
return createDraftStore( { assets: createMemoryAssetStore(), storage: window.localStorage } );
613
+
}
614
+
615
+
describe( 'draft-store', () => {
616
+
it( 'round-trips a draft including held image + cover bytes', async () => {
617
+
const store = newStore();
618
+
await store.save( draft() );
619
+
// Image bytes must NOT sit in localStorage (only the token skeleton).
620
+
expect( window.localStorage.getItem( 'skypress:write:draft' ) ).not.toContain( 'base64' );
621
+
const loaded = await store.load();
622
+
expect( loaded ).toEqual( draft() );
623
+
} );
624
+
625
+
it( 'returns null when nothing is saved', async () => {
626
+
expect( await newStore().load() ).toBe( null );
627
+
} );
628
+
629
+
it( 'clear() removes the draft and its assets', async () => {
630
+
const store = newStore();
631
+
await store.save( draft() );
632
+
await store.clear();
633
+
expect( await store.load() ).toBe( null );
634
+
} );
635
+
636
+
it( 'publish intent is one-shot (set, then consumed once)', () => {
637
+
const store = newStore();
638
+
expect( store.consumePublishIntent() ).toBe( false );
639
+
store.setPublishIntent();
640
+
expect( store.consumePublishIntent() ).toBe( true );
641
+
expect( store.consumePublishIntent() ).toBe( false );
642
+
} );
643
+
} );
644
+
```
645
+
646
+
- [ ] **Step 2: Run test to verify it fails**
647
+
648
+
Run: `npx vitest run src/lib/write/draft-store.test.ts`
649
+
Expected: FAIL — cannot resolve `./draft-store`.
650
+
651
+
- [ ] **Step 3: Write the implementation**
652
+
653
+
```ts
654
+
// src/lib/write/draft-store.ts
655
+
import type { BlockNode } from '../blocks/render';
656
+
import { splitAssets, mergeAssets, type AssetSkeleton } from './held-assets';
657
+
import {
658
+
createIndexedDbAssetStore,
659
+
createMemoryAssetStore,
660
+
type AssetStore,
661
+
} from './asset-store';
662
+
663
+
const DRAFT_KEY = 'skypress:write:draft';
664
+
const INTENT_KEY = 'skypress:write:publish-intent';
665
+
666
+
/** The editor content the writing-first flow persists across the OAuth redirect. */
667
+
export interface WriteDraft {
668
+
title: string;
669
+
lede: string;
670
+
blocks: BlockNode[];
671
+
coverDataUrl: string | null;
672
+
}
673
+
674
+
interface StoredMeta {
675
+
title: string;
676
+
lede: string;
677
+
skeleton: AssetSkeleton;
678
+
}
679
+
680
+
export interface DraftStore {
681
+
save( draft: WriteDraft ): Promise< void >;
682
+
load(): Promise< WriteDraft | null >;
683
+
clear(): Promise< void >;
684
+
setPublishIntent(): void;
685
+
/** Reads the intent flag and clears it — true at most once per set. */
686
+
consumePublishIntent(): boolean;
687
+
}
688
+
689
+
/**
690
+
* Persist the writing-first draft so it survives the full-page OAuth redirect. Light metadata
691
+
* and the token-skeletoned block tree go in `localStorage`; the heavy image bytes (data: URLs)
692
+
* go in the injected `AssetStore` (IndexedDB in the browser). `setPublishIntent` records that
693
+
* the writer hit Publish before the redirect, so the flow auto-resumes on return.
694
+
*/
695
+
export function createDraftStore( opts: { assets?: AssetStore; storage?: Storage } = {} ): DraftStore {
696
+
const storage = opts.storage ?? window.localStorage;
697
+
const assets = opts.assets ?? createIndexedDbAssetStore();
698
+
699
+
return {
700
+
async save( draft ) {
701
+
const { skeleton, assets: bytes } = splitAssets( draft.blocks, draft.coverDataUrl );
702
+
await assets.clear();
703
+
await assets.put( bytes );
704
+
const meta: StoredMeta = { title: draft.title, lede: draft.lede, skeleton };
705
+
storage.setItem( DRAFT_KEY, JSON.stringify( meta ) );
706
+
},
707
+
async load() {
708
+
const raw = storage.getItem( DRAFT_KEY );
709
+
if ( ! raw ) {
710
+
return null;
711
+
}
712
+
let meta: StoredMeta;
713
+
try {
714
+
meta = JSON.parse( raw ) as StoredMeta;
715
+
} catch {
716
+
return null;
717
+
}
718
+
const bytes = await assets.getAll();
719
+
const { blocks, coverDataUrl } = mergeAssets( meta.skeleton, bytes );
720
+
return { title: meta.title, lede: meta.lede, blocks, coverDataUrl };
721
+
},
722
+
async clear() {
723
+
storage.removeItem( DRAFT_KEY );
724
+
await assets.clear();
725
+
},
726
+
setPublishIntent() {
727
+
storage.setItem( INTENT_KEY, '1' );
728
+
},
729
+
consumePublishIntent() {
730
+
const had = storage.getItem( INTENT_KEY ) === '1';
731
+
storage.removeItem( INTENT_KEY );
732
+
return had;
733
+
},
734
+
};
735
+
}
736
+
737
+
export { createMemoryAssetStore };
738
+
```
739
+
740
+
- [ ] **Step 4: Run test to verify it passes**
741
+
742
+
Run: `npx vitest run src/lib/write/draft-store.test.ts`
743
+
Expected: PASS.
744
+
745
+
- [ ] **Step 5: Commit**
746
+
747
+
```bash
748
+
git add src/lib/write/draft-store.ts src/lib/write/draft-store.test.ts
749
+
git commit --no-gpg-sign -m "Add draft store that survives the OAuth redirect"
750
+
```
751
+
752
+
---
753
+
754
+
### Task 5: Upload held assets at publish
755
+
756
+
After sign-in, turn the held `data:` images (+ cover) into committed PDS blobs and a publish-ready block tree. Reuses `attachBlobRefs` so the persisted block shape matches the eager path exactly.
757
+
758
+
**Files:**
759
+
- Create: `src/lib/write/upload-held.ts`
760
+
- Test: `src/lib/write/upload-held.test.ts`
761
+
762
+
**Interfaces:**
763
+
- Consumes: `isDataUrl`, `dataUrlToBlob` from `./held-assets`; `attachBlobRefs`, `buildGetBlobUrl`, `BlobRefJson`, `BlobUpload` from `../media/blob`; `BlockNode`; `Agent` from `@atproto/api`.
764
+
- Produces:
765
+
- `export interface PreparedPublishContent { blocks: BlockNode[]; coverImage?: BlobRefJson }`
766
+
- `export async function uploadHeldAssets( agent: Agent, input: { blocks: BlockNode[]; coverDataUrl: string | null; did: string; pdsUrl: string } ): Promise< PreparedPublishContent >`
767
+
768
+
- [ ] **Step 1: Write the failing test**
769
+
770
+
```ts
771
+
// src/lib/write/upload-held.test.ts
772
+
import { describe, it, expect, vi } from 'vitest';
773
+
import type { Agent } from '@atproto/api';
774
+
import { uploadHeldAssets } from './upload-held';
775
+
import type { BlockNode } from '../blocks/render';
776
+
777
+
const DATA = 'data:image/png;base64,QUFB'; // "AAA"
778
+
779
+
function fakeAgent() {
780
+
const uploadBlob = vi.fn( async ( _file: Blob ) => ( {
781
+
data: { blob: { ref: { toString: () => 'bafyCID' }, mimeType: 'image/png', size: 3 } },
782
+
} ) );
783
+
return { agent: { uploadBlob } as unknown as Agent, uploadBlob };
784
+
}
785
+
786
+
describe( 'uploadHeldAssets', () => {
787
+
it( 'uploads each held image, attaches skypressBlob + a getBlob url, leaves externals alone', async () => {
788
+
const { agent, uploadBlob } = fakeAgent();
789
+
const blocks: BlockNode[] = [
790
+
{ name: 'core/image', attributes: { url: DATA }, innerBlocks: [] },
791
+
{ name: 'core/image', attributes: { url: 'https://ext/x.png' }, innerBlocks: [] },
792
+
];
793
+
794
+
const out = await uploadHeldAssets( agent, {
795
+
blocks,
796
+
coverDataUrl: null,
797
+
did: 'did:plc:me',
798
+
pdsUrl: 'https://pds.example.com',
799
+
} );
800
+
801
+
expect( uploadBlob ).toHaveBeenCalledTimes( 1 );
802
+
expect( out.blocks[ 0 ].attributes!.skypressBlob ).toEqual( {
803
+
$type: 'blob',
804
+
ref: { $link: 'bafyCID' },
805
+
mimeType: 'image/png',
806
+
size: 3,
807
+
} );
808
+
expect( out.blocks[ 0 ].attributes!.url ).toBe(
809
+
'https://pds.example.com/xrpc/com.atproto.sync.getBlob?did=did%3Aplc%3Ame&cid=bafyCID'
810
+
);
811
+
expect( out.blocks[ 1 ].attributes!.url ).toBe( 'https://ext/x.png' );
812
+
expect( out.coverImage ).toBeUndefined();
813
+
} );
814
+
815
+
it( 'uploads a held cover into a BlobRefJson', async () => {
816
+
const { agent } = fakeAgent();
817
+
const out = await uploadHeldAssets( agent, {
818
+
blocks: [],
819
+
coverDataUrl: DATA,
820
+
did: 'did:plc:me',
821
+
pdsUrl: 'https://pds.example.com',
822
+
} );
823
+
expect( out.coverImage ).toEqual( {
824
+
$type: 'blob',
825
+
ref: { $link: 'bafyCID' },
826
+
mimeType: 'image/png',
827
+
size: 3,
828
+
} );
829
+
} );
830
+
} );
831
+
```
832
+
833
+
- [ ] **Step 2: Run test to verify it fails**
834
+
835
+
Run: `npx vitest run src/lib/write/upload-held.test.ts`
836
+
Expected: FAIL — cannot resolve `./upload-held`.
837
+
838
+
- [ ] **Step 3: Write the implementation**
839
+
840
+
```ts
841
+
// src/lib/write/upload-held.ts
842
+
import type { Agent } from '@atproto/api';
843
+
import type { BlockNode } from '../blocks/render';
844
+
import {
845
+
attachBlobRefs,
846
+
buildGetBlobUrl,
847
+
type BlobRefJson,
848
+
type BlobUpload,
849
+
} from '../media/blob';
850
+
import { isDataUrl, dataUrlToBlob } from './held-assets';
851
+
852
+
export interface PreparedPublishContent {
853
+
blocks: BlockNode[];
854
+
coverImage?: BlobRefJson;
855
+
}
856
+
857
+
/** Upload one held `data:` URL to the PDS and return its portable blob ref + getBlob URL. */
858
+
async function uploadOne(
859
+
agent: Agent,
860
+
dataUrl: string,
861
+
did: string,
862
+
pdsUrl: string
863
+
): Promise< BlobUpload > {
864
+
const blob = dataUrlToBlob( dataUrl );
865
+
const res = await agent.uploadBlob( blob, { encoding: blob.type } );
866
+
const out = res.data.blob;
867
+
const cid = out.ref.toString();
868
+
return {
869
+
ref: { $type: 'blob', ref: { $link: cid }, mimeType: out.mimeType, size: out.size },
870
+
url: buildGetBlobUrl( pdsUrl, did, cid ),
871
+
};
872
+
}
873
+
874
+
/**
875
+
* Publish-time bridge for the writing-first flow: walk the block tree, upload every held
876
+
* (`data:`) image to the writer's PDS, and rewrite those blocks via `attachBlobRefs` so they
877
+
* carry `skypressBlob` + a portable getBlob URL (byte-identical to the eager path). External
878
+
* image URLs are left untouched. A held cover is uploaded into a `BlobRefJson` for the document
879
+
* record. Each distinct data URL uploads once.
880
+
*/
881
+
export async function uploadHeldAssets(
882
+
agent: Agent,
883
+
input: { blocks: BlockNode[]; coverDataUrl: string | null; did: string; pdsUrl: string }
884
+
): Promise< PreparedPublishContent > {
885
+
const { blocks, coverDataUrl, did, pdsUrl } = input;
886
+
887
+
// Collect every distinct held image URL in the tree (depth-first), upload once each.
888
+
const registry = new Map< string, BlobUpload >();
889
+
const collect = ( nodes: BlockNode[] ): string[] =>
890
+
nodes.flatMap( ( node ) => {
891
+
const url = node.attributes?.url;
892
+
const here = node.name === 'core/image' && isDataUrl( url ) ? [ url as string ] : [];
893
+
return [ ...here, ...collect( node.innerBlocks ?? [] ) ];
894
+
} );
895
+
896
+
for ( const url of new Set( collect( blocks ) ) ) {
897
+
registry.set( url, await uploadOne( agent, url, did, pdsUrl ) );
898
+
}
899
+
900
+
const prepared = attachBlobRefs( blocks, ( url ) => registry.get( url ) );
901
+
902
+
let coverImage: BlobRefJson | undefined;
903
+
if ( isDataUrl( coverDataUrl ) ) {
904
+
coverImage = ( await uploadOne( agent, coverDataUrl, did, pdsUrl ) ).ref;
905
+
}
906
+
907
+
return { blocks: prepared, coverImage };
908
+
}
909
+
```
910
+
911
+
- [ ] **Step 4: Run test to verify it passes**
912
+
913
+
Run: `npx vitest run src/lib/write/upload-held.test.ts`
914
+
Expected: PASS.
915
+
916
+
- [ ] **Step 5: Commit**
917
+
918
+
```bash
919
+
git add src/lib/write/upload-held.ts src/lib/write/upload-held.test.ts
920
+
git commit --no-gpg-sign -m "Upload held images + cover to the PDS at publish time"
921
+
```
922
+
923
+
---
924
+
925
+
### Task 6: WritePublishFlow component
926
+
927
+
The publish stepper. Given a signed-in agent and the writer's publications, it branches: zero → inline `PublicationForm`; one → confirm; many → pick then confirm. The confirm step discloses the public Bluesky post (and notified mentions) and enforces the 300-grapheme limit. On confirm it uploads held assets then calls `publish()`.
928
+
929
+
**Files:**
930
+
- Create: `src/components/WritePublishFlow.tsx`
931
+
- Test: `src/components/WritePublishFlow.test.tsx`
932
+
933
+
**Interfaces:**
934
+
- Consumes: `uploadHeldAssets` from `../lib/write/upload-held`; `publish`, `Identity` from `../lib/publish/publisher`; `Publication` from `../lib/publish/publications`; `computePostPreview` from `./PublishPanel`; `PublicationForm` from `./PublicationForm`; `BlockNode`; `Agent`.
935
+
- Produces:
936
+
- `interface Props { agent: Agent; identity: Identity; pdsUrl: string; blocks: BlockNode[]; coverDataUrl: string | null; title: string; description: string; publications: Publication[] | null; onReloadPublications: () => void; onPublished: ( result: { articleUrl: string } ) => void; onCancel: () => void; }`
937
+
- `export default function WritePublishFlow( props: Props )`
938
+
939
+
- [ ] **Step 1: Write the failing test**
940
+
941
+
```tsx
942
+
// src/components/WritePublishFlow.test.tsx
943
+
import { describe, it, expect, vi, beforeEach } from 'vitest';
944
+
import { act, createElement } from 'react';
945
+
import { createRoot } from 'react-dom/client';
946
+
import type { Agent } from '@atproto/api';
947
+
948
+
( globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean } ).IS_REACT_ACT_ENVIRONMENT = true;
949
+
950
+
const { publish, uploadHeldAssets } = vi.hoisted( () => ( {
951
+
publish: vi.fn( async () => ( { articleUrl: 'https://x/a' } ) ),
952
+
uploadHeldAssets: vi.fn( async () => ( { blocks: [], coverImage: undefined } ) ),
953
+
} ) );
954
+
vi.mock( '../lib/publish/publisher', () => ( { publish } ) );
955
+
vi.mock( '../lib/write/upload-held', () => ( { uploadHeldAssets } ) );
956
+
957
+
import WritePublishFlow from './WritePublishFlow';
958
+
import type { BlockNode } from '../lib/blocks/render';
959
+
960
+
const PUB = ( uri: string, name: string ) => ( {
961
+
uri, cid: 'cid', rkey: uri.split( '/' ).pop()!, slug: name, name,
962
+
} );
963
+
const BLOCKS: BlockNode[] = [ { name: 'core/paragraph', attributes: { content: 'Body' }, innerBlocks: [] } ];
964
+
965
+
function mount( publications: unknown ) {
966
+
const onPublished = vi.fn();
967
+
const container = document.createElement( 'div' );
968
+
document.body.appendChild( container );
969
+
const root = createRoot( container );
970
+
act( () => {
971
+
root.render(
972
+
createElement( WritePublishFlow, {
973
+
agent: {} as Agent,
974
+
identity: { did: 'did:plc:me', handle: 'me.test' },
975
+
pdsUrl: 'https://pds',
976
+
blocks: BLOCKS,
977
+
coverDataUrl: null,
978
+
title: 'Title',
979
+
description: 'Lede',
980
+
publications,
981
+
onReloadPublications: vi.fn(),
982
+
onPublished,
983
+
onCancel: vi.fn(),
984
+
} as never )
985
+
);
986
+
} );
987
+
return { container, root, onPublished };
988
+
}
989
+
990
+
beforeEach( () => {
991
+
publish.mockClear();
992
+
uploadHeldAssets.mockClear();
993
+
} );
994
+
995
+
describe( 'WritePublishFlow', () => {
996
+
it( 'single publication: shows a confirm naming it, never auto-publishes', () => {
997
+
const { container } = mount( [ PUB( 'at://me/site.standard.publication/p1', 'Solo' ) ] );
998
+
expect( container.textContent ).toContain( 'Solo' );
999
+
expect( container.textContent?.toLowerCase() ).toContain( 'bluesky' );
1000
+
expect( publish ).not.toHaveBeenCalled();
1001
+
} );
1002
+
1003
+
it( 'confirming uploads held assets then publishes', async () => {
1004
+
const { container, onPublished } = mount( [ PUB( 'at://me/site.standard.publication/p1', 'Solo' ) ] );
1005
+
const confirm = [ ...container.querySelectorAll( 'button' ) ].find( ( b ) =>
1006
+
/post to bluesky/i.test( b.textContent ?? '' )
1007
+
)!;
1008
+
await act( async () => confirm.dispatchEvent( new MouseEvent( 'click', { bubbles: true } ) ) );
1009
+
expect( uploadHeldAssets ).toHaveBeenCalledTimes( 1 );
1010
+
expect( publish ).toHaveBeenCalledTimes( 1 );
1011
+
expect( onPublished ).toHaveBeenCalledWith( { articleUrl: 'https://x/a' } );
1012
+
} );
1013
+
1014
+
it( 'zero publications: renders the inline create-publication form', () => {
1015
+
const { container } = mount( [] );
1016
+
expect( container.textContent ).toContain( 'New publication' );
1017
+
} );
1018
+
1019
+
it( 'many publications: renders a picker listing each', () => {
1020
+
const { container } = mount( [
1021
+
PUB( 'at://me/site.standard.publication/p1', 'One' ),
1022
+
PUB( 'at://me/site.standard.publication/p2', 'Two' ),
1023
+
] );
1024
+
expect( container.querySelector( 'select' ) ).not.toBe( null );
1025
+
expect( container.textContent ).toContain( 'One' );
1026
+
expect( container.textContent ).toContain( 'Two' );
1027
+
} );
1028
+
} );
1029
+
```
1030
+
1031
+
- [ ] **Step 2: Run test to verify it fails**
1032
+
1033
+
Run: `npx vitest run src/components/WritePublishFlow.test.tsx`
1034
+
Expected: FAIL — cannot resolve `./WritePublishFlow`.
1035
+
1036
+
- [ ] **Step 3: Write the implementation**
1037
+
1038
+
```tsx
1039
+
// src/components/WritePublishFlow.tsx
1040
+
import { useMemo, useState } from 'react';
1041
+
import type { Agent } from '@atproto/api';
1042
+
import { publish, type Identity } from '../lib/publish/publisher';
1043
+
import type { Publication } from '../lib/publish/publications';
1044
+
import { computePostPreview } from './PublishPanel';
1045
+
import PublicationForm from './PublicationForm';
1046
+
import { uploadHeldAssets } from '../lib/write/upload-held';
1047
+
import type { BlockNode } from '../lib/blocks/render';
1048
+
1049
+
interface Props {
1050
+
agent: Agent;
1051
+
identity: Identity;
1052
+
pdsUrl: string;
1053
+
blocks: BlockNode[];
1054
+
coverDataUrl: string | null;
1055
+
title: string;
1056
+
description: string;
1057
+
/** `null` while still loading; `[]` when the writer has none yet. */
1058
+
publications: Publication[] | null;
1059
+
/** Ask the parent to re-list publications (after an inline create). */
1060
+
onReloadPublications: () => void;
1061
+
onPublished: ( result: { articleUrl: string } ) => void;
1062
+
onCancel: () => void;
1063
+
}
1064
+
1065
+
type Phase = 'pick' | 'working' | 'error';
1066
+
1067
+
/**
1068
+
* The writing-first publish stepper (design 2026-06-17). Branches on how many publications the
1069
+
* writer owns: zero → inline create; one → confirm; many → pick then confirm. The confirm step
1070
+
* always discloses the public Bluesky post (brief §10) and blocks an over-limit post. On confirm
1071
+
* it uploads the held images/cover, then reuses `publish()` (document + Bluesky post).
1072
+
*/
1073
+
export default function WritePublishFlow( {
1074
+
agent,
1075
+
identity,
1076
+
pdsUrl,
1077
+
blocks,
1078
+
coverDataUrl,
1079
+
title,
1080
+
description,
1081
+
publications,
1082
+
onReloadPublications,
1083
+
onPublished,
1084
+
onCancel,
1085
+
}: Props ) {
1086
+
const pubs = publications ?? [];
1087
+
const [ targetUri, setTargetUri ] = useState( () => pubs[ 0 ]?.uri ?? '' );
1088
+
const [ phase, setPhase ] = useState< Phase >( 'pick' );
1089
+
const [ error, setError ] = useState< string | null >( null );
1090
+
1091
+
const target = pubs.find( ( p ) => p.uri === targetUri ) ?? pubs[ 0 ];
1092
+
1093
+
const preview = useMemo(
1094
+
() =>
1095
+
target
1096
+
? computePostPreview( {
1097
+
title,
1098
+
lede: description,
1099
+
blocks,
1100
+
handle: identity.handle ?? identity.did,
1101
+
slug: target.slug,
1102
+
} )
1103
+
: null,
1104
+
[ target, title, description, blocks, identity ]
1105
+
);
1106
+
1107
+
if ( publications === null ) {
1108
+
return (
1109
+
<section className="writeflow" aria-label="Publish">
1110
+
<p className="writeflow__status">Loading your publications…</p>
1111
+
</section>
1112
+
);
1113
+
}
1114
+
1115
+
// Zero publications → inline "create your first publication".
1116
+
if ( pubs.length === 0 ) {
1117
+
return (
1118
+
<section className="writeflow" aria-label="Create your first publication">
1119
+
<p className="writeflow__lede">
1120
+
You don't have a publication yet — create one to publish into.
1121
+
</p>
1122
+
<PublicationForm
1123
+
agent={ agent }
1124
+
did={ identity.did }
1125
+
pdsUrl={ pdsUrl }
1126
+
handle={ identity.handle ?? identity.did }
1127
+
onSaved={ ( pub ) => {
1128
+
setTargetUri( pub.uri );
1129
+
onReloadPublications();
1130
+
} }
1131
+
onCancel={ onCancel }
1132
+
/>
1133
+
</section>
1134
+
);
1135
+
}
1136
+
1137
+
async function run() {
1138
+
if ( ! target ) {
1139
+
return;
1140
+
}
1141
+
setPhase( 'working' );
1142
+
setError( null );
1143
+
try {
1144
+
const prepared = await uploadHeldAssets( agent, {
1145
+
blocks,
1146
+
coverDataUrl,
1147
+
did: identity.did,
1148
+
pdsUrl,
1149
+
} );
1150
+
const res = await publish( agent, identity, {
1151
+
title: title.trim(),
1152
+
description,
1153
+
blocks: prepared.blocks,
1154
+
publicationUri: target.uri,
1155
+
publicationCid: target.cid,
1156
+
publicationSlug: target.slug,
1157
+
coverImage: prepared.coverImage,
1158
+
} );
1159
+
onPublished( { articleUrl: res.articleUrl } );
1160
+
} catch ( err ) {
1161
+
setError( err instanceof Error ? err.message : String( err ) );
1162
+
setPhase( 'error' );
1163
+
}
1164
+
}
1165
+
1166
+
const overLimit = Boolean( preview?.overLimit );
1167
+
1168
+
return (
1169
+
<section className="writeflow" aria-label="Publish">
1170
+
{ pubs.length > 1 && (
1171
+
<label className="writeflow__target">
1172
+
<span>Publish to</span>
1173
+
<select
1174
+
value={ target?.uri ?? '' }
1175
+
onChange={ ( e ) => setTargetUri( e.target.value ) }
1176
+
disabled={ phase === 'working' }
1177
+
>
1178
+
{ pubs.map( ( p ) => (
1179
+
<option key={ p.uri } value={ p.uri }>
1180
+
{ p.name }
1181
+
</option>
1182
+
) ) }
1183
+
</select>
1184
+
</label>
1185
+
) }
1186
+
1187
+
<p className="writeflow__warning">
1188
+
Publishing saves this article to <strong>your PDS</strong> and also creates a{ ' ' }
1189
+
<strong>public Bluesky post</strong> linking to it
1190
+
{ target ? <> in <strong>{ target.name }</strong></> : null }. Everyone following you
1191
+
will see it.
1192
+
{ preview && preview.handles.length > 0 && (
1193
+
<> It will notify <strong>{ preview.handles.join( ', ' ) }</strong>.</>
1194
+
) }
1195
+
</p>
1196
+
1197
+
{ overLimit && (
1198
+
<p className="writeflow__count" aria-live="polite">
1199
+
Bluesky post: { preview!.graphemes }/300 — too long to publish; shorten the
1200
+
subtitle or remove a mention.
1201
+
</p>
1202
+
) }
1203
+
1204
+
{ phase === 'working' ? (
1205
+
<p className="writeflow__status">Publishing…</p>
1206
+
) : (
1207
+
<div className="writeflow__actions">
1208
+
<button
1209
+
type="button"
1210
+
className="writeflow__publish"
1211
+
disabled={ overLimit || ! target }
1212
+
onClick={ () => void run() }
1213
+
>
1214
+
Publish & post to Bluesky
1215
+
</button>
1216
+
<button type="button" className="writeflow__cancel" onClick={ onCancel }>
1217
+
Keep editing
1218
+
</button>
1219
+
</div>
1220
+
) }
1221
+
1222
+
{ phase === 'error' && error && (
1223
+
<p className="writeflow__error" role="alert">
1224
+
Publish failed: { error }
1225
+
</p>
1226
+
) }
1227
+
</section>
1228
+
);
1229
+
}
1230
+
```
1231
+
1232
+
- [ ] **Step 4: Run test to verify it passes**
1233
+
1234
+
Run: `npx vitest run src/components/WritePublishFlow.test.tsx`
1235
+
Expected: PASS (all four).
1236
+
1237
+
- [ ] **Step 5: Commit**
1238
+
1239
+
```bash
1240
+
git add src/components/WritePublishFlow.tsx src/components/WritePublishFlow.test.tsx
1241
+
git commit --no-gpg-sign -m "Add WritePublishFlow stepper (branch, confirm, upload, publish)"
1242
+
```
1243
+
1244
+
---
1245
+
1246
+
### Task 7: SignInPanel + AccountPill
1247
+
1248
+
The two top-right corner states. `SignInPanel` is the signed-out handle entry (with the link-out to Bluesky signup); `AccountPill` is the signed-in avatar/handle menu. Both are presentational — the island wires the behavior.
1249
+
1250
+
**Files:**
1251
+
- Create: `src/components/SignInPanel.tsx`
1252
+
- Create: `src/components/AccountPill.tsx`
1253
+
- Test: `src/components/SignInPanel.test.tsx`
1254
+
- Test: `src/components/AccountPill.test.tsx`
1255
+
1256
+
**Interfaces:**
1257
+
- `SignInPanel`: `interface Props { forPublish: boolean; error: string | null; onSubmit: ( value: string ) => void; onCancel?: () => void; }` → `export default function SignInPanel( props: Props )`
1258
+
- `AccountPill`: `interface Props { displayName: string; handle: string | null; avatar: string | null; onSignOut: () => void; }` → `export default function AccountPill( props: Props )` (the Profile link is built from `authorPath( handle )`, omitted when no handle).
1259
+
1260
+
- [ ] **Step 1: Write the failing tests**
1261
+
1262
+
```tsx
1263
+
// src/components/SignInPanel.test.tsx
1264
+
import { describe, it, expect, vi } from 'vitest';
1265
+
import { act, createElement } from 'react';
1266
+
import { createRoot } from 'react-dom/client';
1267
+
1268
+
( globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean } ).IS_REACT_ACT_ENVIRONMENT = true;
1269
+
import SignInPanel from './SignInPanel';
1270
+
1271
+
function mount( props: Record< string, unknown > ) {
1272
+
const container = document.createElement( 'div' );
1273
+
document.body.appendChild( container );
1274
+
act( () => createRoot( container ).render( createElement( SignInPanel, props as never ) ) );
1275
+
return container;
1276
+
}
1277
+
1278
+
describe( 'SignInPanel', () => {
1279
+
it( 'for-publish variant frames the CTA around publishing and links out to signup', () => {
1280
+
const c = mount( { forPublish: true, error: null, onSubmit: vi.fn() } );
1281
+
expect( c.textContent?.toLowerCase() ).toContain( 'publish' );
1282
+
const signup = c.querySelector( 'a[href*="bsky.app"]' );
1283
+
expect( signup ).not.toBe( null );
1284
+
} );
1285
+
1286
+
it( 'submits the typed handle', () => {
1287
+
const onSubmit = vi.fn();
1288
+
const c = mount( { forPublish: false, error: null, onSubmit } );
1289
+
const input = c.querySelector( 'input' )!;
1290
+
const form = c.querySelector( 'form' )!;
1291
+
act( () => {
1292
+
( input as HTMLInputElement ).value = 'alice.bsky.social';
1293
+
input.dispatchEvent( new Event( 'input', { bubbles: true } ) );
1294
+
} );
1295
+
act( () => form.dispatchEvent( new Event( 'submit', { bubbles: true, cancelable: true } ) ) );
1296
+
expect( onSubmit ).toHaveBeenCalledWith( 'alice.bsky.social' );
1297
+
} );
1298
+
1299
+
it( 'shows an error when provided', () => {
1300
+
const c = mount( { forPublish: false, error: 'Bad handle', onSubmit: vi.fn() } );
1301
+
expect( c.textContent ).toContain( 'Bad handle' );
1302
+
} );
1303
+
} );
1304
+
```
1305
+
1306
+
```tsx
1307
+
// src/components/AccountPill.test.tsx
1308
+
import { describe, it, expect, vi } from 'vitest';
1309
+
import { act, createElement } from 'react';
1310
+
import { createRoot } from 'react-dom/client';
1311
+
1312
+
( globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean } ).IS_REACT_ACT_ENVIRONMENT = true;
1313
+
import AccountPill from './AccountPill';
1314
+
1315
+
function mount( props: Record< string, unknown > ) {
1316
+
const container = document.createElement( 'div' );
1317
+
document.body.appendChild( container );
1318
+
act( () => createRoot( container ).render( createElement( AccountPill, props as never ) ) );
1319
+
return container;
1320
+
}
1321
+
1322
+
describe( 'AccountPill', () => {
1323
+
it( 'shows the handle and a Manage-publications + Profile + Sign out menu', () => {
1324
+
const c = mount( {
1325
+
displayName: 'Alice', handle: 'alice.test', avatar: null, onSignOut: vi.fn(),
1326
+
} );
1327
+
expect( c.textContent ).toContain( 'alice.test' );
1328
+
expect( c.querySelector( 'a[href="/dashboard"]' ) ).not.toBe( null );
1329
+
expect( c.querySelector( 'a[href="/@alice.test"]' ) ).not.toBe( null );
1330
+
expect( c.textContent?.toLowerCase() ).toContain( 'sign out' );
1331
+
} );
1332
+
1333
+
it( 'invokes onSignOut when Sign out is clicked', () => {
1334
+
const onSignOut = vi.fn();
1335
+
const c = mount( { displayName: 'Alice', handle: 'alice.test', avatar: null, onSignOut } );
1336
+
const btn = [ ...c.querySelectorAll( 'button' ) ].find( ( b ) => /sign out/i.test( b.textContent ?? '' ) )!;
1337
+
act( () => btn.dispatchEvent( new MouseEvent( 'click', { bubbles: true } ) ) );
1338
+
expect( onSignOut ).toHaveBeenCalledTimes( 1 );
1339
+
} );
1340
+
1341
+
it( 'omits the Profile link when no handle is known', () => {
1342
+
const c = mount( { displayName: 'did:plc:me', handle: null, avatar: null, onSignOut: vi.fn() } );
1343
+
expect( c.querySelector( 'a[href^="/@"]' ) ).toBe( null );
1344
+
} );
1345
+
} );
1346
+
```
1347
+
1348
+
- [ ] **Step 2: Run tests to verify they fail**
1349
+
1350
+
Run: `npx vitest run src/components/SignInPanel.test.tsx src/components/AccountPill.test.tsx`
1351
+
Expected: FAIL — cannot resolve the components.
1352
+
1353
+
- [ ] **Step 3: Write the implementations**
1354
+
1355
+
```tsx
1356
+
// src/components/SignInPanel.tsx
1357
+
import { useState } from 'react';
1358
+
1359
+
interface Props {
1360
+
/** True when opened from "Publish" — the copy promises a publish on return. */
1361
+
forPublish: boolean;
1362
+
error: string | null;
1363
+
onSubmit: ( value: string ) => void;
1364
+
onCancel?: () => void;
1365
+
}
1366
+
1367
+
/**
1368
+
* Signed-out handle entry for the writing-first flow. OAuth is sign-in only, so this never
1369
+
* creates an account — it links out to Bluesky's hosted signup instead (brief guardrail). The
1370
+
* caller persists the draft + sets publish intent before the redirect.
1371
+
*/
1372
+
export default function SignInPanel( { forPublish, error, onSubmit, onCancel }: Props ) {
1373
+
const [ value, setValue ] = useState( '' );
1374
+
1375
+
return (
1376
+
<form
1377
+
className="signin-panel"
1378
+
onSubmit={ ( event ) => {
1379
+
event.preventDefault();
1380
+
onSubmit( value.trim() );
1381
+
} }
1382
+
>
1383
+
<h2 className="signin-panel__title">
1384
+
{ forPublish ? 'Sign in to publish' : 'Sign in' }
1385
+
</h2>
1386
+
<p className="signin-panel__lede">
1387
+
{ forPublish
1388
+
? "Your draft is saved. Sign in and we'll pick up right where you left off and publish it."
1389
+
: 'Use your existing Bluesky / AT Protocol identity. Your work stays in your own account.' }
1390
+
</p>
1391
+
<label className="signin-panel__label" htmlFor="write-handle">
1392
+
Your handle, DID, or PDS URL
1393
+
</label>
1394
+
<input
1395
+
id="write-handle"
1396
+
className="signin-panel__input"
1397
+
name="handle"
1398
+
autoComplete="username"
1399
+
autoCapitalize="none"
1400
+
autoCorrect="off"
1401
+
spellCheck={ false }
1402
+
placeholder="alice.bsky.social"
1403
+
value={ value }
1404
+
onChange={ ( event ) => setValue( event.target.value ) }
1405
+
/>
1406
+
<div className="signin-panel__actions">
1407
+
<button className="signin-panel__submit" type="submit">
1408
+
Sign in with AT Protocol
1409
+
</button>
1410
+
{ onCancel && (
1411
+
<button className="signin-panel__cancel" type="button" onClick={ onCancel }>
1412
+
Cancel
1413
+
</button>
1414
+
) }
1415
+
</div>
1416
+
{ error && (
1417
+
<p className="signin-panel__error" role="alert">
1418
+
{ error }
1419
+
</p>
1420
+
) }
1421
+
<p className="signin-panel__signup">
1422
+
Need an account?{ ' ' }
1423
+
<a href="https://bsky.app" target="_blank" rel="noreferrer noopener">
1424
+
Create one on Bluesky →
1425
+
</a>
1426
+
</p>
1427
+
</form>
1428
+
);
1429
+
}
1430
+
```
1431
+
1432
+
```tsx
1433
+
// src/components/AccountPill.tsx
1434
+
import { useEffect, useRef, useState } from 'react';
1435
+
import { authorPath } from '../lib/auth/profile';
1436
+
1437
+
interface Props {
1438
+
displayName: string;
1439
+
handle: string | null;
1440
+
avatar: string | null;
1441
+
onSignOut: () => void;
1442
+
}
1443
+
1444
+
/**
1445
+
* Signed-in account pill for the writing-first page: avatar + handle, opening a menu with
1446
+
* Manage publications (→ existing dashboard), Profile (public author page, omitted when no
1447
+
* handle), and Sign out. Management lives on the dashboard by design — the editor stays the
1448
+
* focus here (design 2026-06-17, Q5).
1449
+
*/
1450
+
export default function AccountPill( { displayName, handle, avatar, onSignOut }: Props ) {
1451
+
const [ open, setOpen ] = useState( false );
1452
+
const [ avatarOk, setAvatarOk ] = useState( true );
1453
+
const rootRef = useRef< HTMLDivElement >( null );
1454
+
1455
+
useEffect( () => {
1456
+
if ( ! open ) {
1457
+
return;
1458
+
}
1459
+
function onDown( event: MouseEvent ) {
1460
+
if ( rootRef.current && ! rootRef.current.contains( event.target as Node ) ) {
1461
+
setOpen( false );
1462
+
}
1463
+
}
1464
+
document.addEventListener( 'mousedown', onDown );
1465
+
return () => document.removeEventListener( 'mousedown', onDown );
1466
+
}, [ open ] );
1467
+
1468
+
const profileHref = authorPath( handle );
1469
+
1470
+
return (
1471
+
<div className="account-pill" ref={ rootRef }>
1472
+
<button
1473
+
type="button"
1474
+
className="account-pill__trigger"
1475
+
aria-haspopup="menu"
1476
+
aria-expanded={ open }
1477
+
onClick={ () => setOpen( ( v ) => ! v ) }
1478
+
>
1479
+
{ avatar && avatarOk ? (
1480
+
<img
1481
+
className="account-pill__avatar"
1482
+
src={ avatar }
1483
+
alt=""
1484
+
width={ 28 }
1485
+
height={ 28 }
1486
+
onError={ () => setAvatarOk( false ) }
1487
+
/>
1488
+
) : (
1489
+
<span className="account-pill__avatar account-pill__avatar--fallback" aria-hidden="true">
1490
+
{ displayName.charAt( 0 ).toUpperCase() }
1491
+
</span>
1492
+
) }
1493
+
<span className="account-pill__handle">
1494
+
{ handle ? `@${ handle }` : displayName }
1495
+
</span>
1496
+
</button>
1497
+
{ open && (
1498
+
<div className="account-pill__menu" role="menu">
1499
+
<a className="account-pill__item" role="menuitem" href="/dashboard">
1500
+
Manage publications
1501
+
</a>
1502
+
{ profileHref && (
1503
+
<a className="account-pill__item" role="menuitem" href={ profileHref }>
1504
+
Profile
1505
+
</a>
1506
+
) }
1507
+
<button
1508
+
type="button"
1509
+
className="account-pill__item account-pill__item--button"
1510
+
role="menuitem"
1511
+
onClick={ onSignOut }
1512
+
>
1513
+
Sign out
1514
+
</button>
1515
+
</div>
1516
+
) }
1517
+
</div>
1518
+
);
1519
+
}
1520
+
```
1521
+
1522
+
- [ ] **Step 4: Run tests to verify they pass**
1523
+
1524
+
Run: `npx vitest run src/components/SignInPanel.test.tsx src/components/AccountPill.test.tsx`
1525
+
Expected: PASS.
1526
+
1527
+
- [ ] **Step 5: Commit**
1528
+
1529
+
```bash
1530
+
git add src/components/SignInPanel.tsx src/components/AccountPill.tsx \
1531
+
src/components/SignInPanel.test.tsx src/components/AccountPill.test.tsx
1532
+
git commit --no-gpg-sign -m "Add signed-out sign-in panel and signed-in account pill"
1533
+
```
1534
+
1535
+
---
1536
+
1537
+
### Task 8: WriteStudio island
1538
+
1539
+
The island that ties it together: editor for every auth status, deferred media, draft persistence + auto-restore, the Publish action (persist + intent + redirect when signed out), and the resume-after-redirect that auto-opens `WritePublishFlow`.
1540
+
1541
+
**Files:**
1542
+
- Create: `src/components/WriteStudio.tsx`
1543
+
- Test: `src/components/WriteStudio.test.tsx`
1544
+
1545
+
**Interfaces:**
1546
+
- Consumes: `AuthProvider`, `useAuth`; `SkyEditor`; `AppBar`; `PublishedPill`; `CoverImagePicker`; `SignInPanel`; `AccountPill`; `WritePublishFlow`; `createDeferredMediaUpload`; `createDraftStore`, `WriteDraft`; `listPublications`, `Publication`; `normalizeBlocks` from `../lib/publish/records`; `validateCoverFile`, `CoverUpload` from `../lib/media/cover`; `displayNameFor` from `../lib/auth/profile`; `BlockNode`.
1547
+
- Produces: `export default function WriteStudio()` (default export, mounted by the route).
1548
+
1549
+
> **Cover handling note:** in this flow a chosen cover is held as a `data:` URL. `CoverImagePicker` needs a `CoverUpload` (`{ ref, previewUrl }`); we pass a deferred placeholder ref (`{ $type: 'blob', ref: { $link: '' }, mimeType: file.type, size: file.size }`) and a `data:` URL `previewUrl`. Only `previewUrl` is read downstream — `WritePublishFlow` receives `coverDataUrl = cover?.previewUrl ?? null` and `uploadHeldAssets` produces the real ref at publish.
1550
+
1551
+
> **Editor seeding note:** `WriteStudio` keeps content as `BlockNode[]` (`blocks`). `SkyEditor.onChange` yields `BlockInstance[]`; convert with `normalizeBlocks` before storing. On restore, pass the restored nodes once as `SkyEditor`'s `initialBlocks` (captured in a ref so a later `blocks` change doesn't remount the canvas).
1552
+
1553
+
- [ ] **Step 1: Write the failing test** (mock `SkyEditor`, `draft-store`, and `listPublications` so the heavy editor and storage are out of scope; assert the auth-state surfaces + resume)
1554
+
1555
+
```tsx
1556
+
// src/components/WriteStudio.test.tsx
1557
+
import { describe, it, expect, vi, beforeEach } from 'vitest';
1558
+
import { act, createElement } from 'react';
1559
+
import { createRoot } from 'react-dom/client';
1560
+
1561
+
( globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean } ).IS_REACT_ACT_ENVIRONMENT = true;
1562
+
1563
+
// Stub the heavy editor: render a marker, ignore props.
1564
+
vi.mock( './SkyEditor', () => ( { default: () => createElement( 'div', { 'data-testid': 'sky-editor' } ) } ) );
1565
+
// Stub AppBar to avoid pulling chrome we don't assert on.
1566
+
vi.mock( './AppBar', () => ( { default: () => null } ) );
1567
+
1568
+
const auth = vi.hoisted( () => ( { value: {} as Record< string, unknown > } ) );
1569
+
vi.mock( '../lib/auth/AuthProvider', () => ( {
1570
+
AuthProvider: ( { children }: { children: unknown } ) => children,
1571
+
} ) );
1572
+
vi.mock( '../lib/auth/useAuth', () => ( { useAuth: () => auth.value } ) );
1573
+
1574
+
const draft = vi.hoisted( () => ( {
1575
+
store: {
1576
+
load: vi.fn( async () => null ),
1577
+
save: vi.fn( async () => {} ),
1578
+
clear: vi.fn( async () => {} ),
1579
+
setPublishIntent: vi.fn(),
1580
+
consumePublishIntent: vi.fn( () => false ),
1581
+
},
1582
+
} ) );
1583
+
vi.mock( '../lib/write/draft-store', () => ( {
1584
+
createDraftStore: () => draft.store,
1585
+
} ) );
1586
+
vi.mock( '../lib/publish/publications', () => ( {
1587
+
listPublications: vi.fn( async () => [] ),
1588
+
} ) );
1589
+
1590
+
import WriteStudio from './WriteStudio';
1591
+
1592
+
function render() {
1593
+
const container = document.createElement( 'div' );
1594
+
document.body.appendChild( container );
1595
+
const root = createRoot( container );
1596
+
return { container, root };
1597
+
}
1598
+
1599
+
beforeEach( () => {
1600
+
draft.store.consumePublishIntent.mockReturnValue( false );
1601
+
draft.store.load.mockResolvedValue( null );
1602
+
} );
1603
+
1604
+
describe( 'WriteStudio', () => {
1605
+
it( 'signed out: renders the editor AND a sign-in affordance (no gate)', async () => {
1606
+
auth.value = { status: 'signed-out', agent: null, did: null, handle: null, signIn: vi.fn(), signOut: vi.fn() };
1607
+
const { container, root } = render();
1608
+
await act( async () => {
1609
+
root.render( createElement( WriteStudio ) );
1610
+
} );
1611
+
expect( container.querySelector( '[data-testid="sky-editor"]' ) ).not.toBe( null );
1612
+
expect( container.textContent?.toLowerCase() ).toContain( 'sign in' );
1613
+
} );
1614
+
1615
+
it( 'signed in: renders the editor AND the account pill', async () => {
1616
+
auth.value = {
1617
+
status: 'signed-in', agent: {}, did: 'did:plc:me', handle: 'me.test',
1618
+
displayName: 'Me', avatar: null, pdsUrl: 'https://pds', signIn: vi.fn(), signOut: vi.fn(),
1619
+
};
1620
+
const { container, root } = render();
1621
+
await act( async () => {
1622
+
root.render( createElement( WriteStudio ) );
1623
+
} );
1624
+
expect( container.querySelector( '[data-testid="sky-editor"]' ) ).not.toBe( null );
1625
+
expect( container.querySelector( '.account-pill' ) ).not.toBe( null );
1626
+
} );
1627
+
1628
+
it( 'resume: a publish intent on a signed-in load opens the publish flow', async () => {
1629
+
draft.store.consumePublishIntent.mockReturnValue( true );
1630
+
auth.value = {
1631
+
status: 'signed-in', agent: {}, did: 'did:plc:me', handle: 'me.test',
1632
+
displayName: 'Me', avatar: null, pdsUrl: 'https://pds', signIn: vi.fn(), signOut: vi.fn(),
1633
+
};
1634
+
const { container, root } = render();
1635
+
await act( async () => {
1636
+
root.render( createElement( WriteStudio ) );
1637
+
} );
1638
+
expect( container.querySelector( '.writeflow' ) ).not.toBe( null );
1639
+
} );
1640
+
} );
1641
+
```
1642
+
1643
+
- [ ] **Step 2: Run test to verify it fails**
1644
+
1645
+
Run: `npx vitest run src/components/WriteStudio.test.tsx`
1646
+
Expected: FAIL — cannot resolve `./WriteStudio`.
1647
+
1648
+
- [ ] **Step 3: Write the implementation**
1649
+
1650
+
```tsx
1651
+
// src/components/WriteStudio.tsx
1652
+
import { useEffect, useMemo, useRef, useState } from 'react';
1653
+
import type { BlockInstance } from '@wordpress/blocks';
1654
+
import { AuthProvider } from '../lib/auth/AuthProvider';
1655
+
import { useAuth } from '../lib/auth/useAuth';
1656
+
import SkyEditor from './SkyEditor';
1657
+
import AppBar from './AppBar';
1658
+
import PublishedPill from './PublishedPill';
1659
+
import CoverImagePicker from './CoverImagePicker';
1660
+
import SignInPanel from './SignInPanel';
1661
+
import AccountPill from './AccountPill';
1662
+
import WritePublishFlow from './WritePublishFlow';
1663
+
import { createDeferredMediaUpload } from '../lib/write/deferred-media';
1664
+
import { createDraftStore, type WriteDraft } from '../lib/write/draft-store';
1665
+
import { listPublications, type Publication } from '../lib/publish/publications';
1666
+
import { normalizeBlocks } from '../lib/publish/records';
1667
+
import { validateCoverFile, type CoverUpload } from '../lib/media/cover';
1668
+
import { displayNameFor } from '../lib/auth/profile';
1669
+
import type { BlockNode } from '../lib/blocks/render';
1670
+
import type { BlobRefJson } from '../lib/media/blob';
1671
+
1672
+
/** Read a file into a `data:` URL for a held (not-yet-uploaded) cover preview. */
1673
+
function readAsDataUrl( file: File ): Promise< string > {
1674
+
return new Promise( ( resolve, reject ) => {
1675
+
const reader = new FileReader();
1676
+
reader.onload = () => resolve( reader.result as string );
1677
+
reader.onerror = () => reject( reader.error ?? new Error( 'Could not read the file.' ) );
1678
+
reader.readAsDataURL( file );
1679
+
} );
1680
+
}
1681
+
1682
+
/** A placeholder ref for a held cover — only `previewUrl` (a data URL) is used before publish. */
1683
+
function deferredCoverRef( file: File ): BlobRefJson {
1684
+
return { $type: 'blob', ref: { $link: '' }, mimeType: file.type, size: file.size };
1685
+
}
1686
+
1687
+
function WriteSurface() {
1688
+
const { status, agent, did, handle, displayName, avatar, pdsUrl, error, signIn, signOut } =
1689
+
useAuth();
1690
+
1691
+
const draftStore = useMemo( () => createDraftStore(), [] );
1692
+
const mediaUpload = useMemo( () => createDeferredMediaUpload(), [] );
1693
+
1694
+
const [ title, setTitle ] = useState( '' );
1695
+
const [ lede, setLede ] = useState( '' );
1696
+
const [ blocks, setBlocks ] = useState< BlockNode[] >( [] );
1697
+
const [ cover, setCover ] = useState< CoverUpload | null >( null );
1698
+
const [ publications, setPublications ] = useState< Publication[] | null >( null );
1699
+
const [ flowOpen, setFlowOpen ] = useState( false );
1700
+
const [ pendingPublish, setPendingPublish ] = useState( false );
1701
+
const [ signinOpen, setSigninOpen ] = useState( false );
1702
+
const [ published, setPublished ] = useState< { url: string } | null >( null );
1703
+
const [ editorKey, setEditorKey ] = useState( 0 );
1704
+
1705
+
// Restored content fed to the editor canvas once, captured so a later `blocks`
1706
+
// change can't remount SkyEditor (which would wipe the canvas).
1707
+
const initialBlocksRef = useRef< BlockNode[] >( [] );
1708
+
const restoredRef = useRef( false );
1709
+
const intentRef = useRef( false );
1710
+
1711
+
// One-shot restore + intent read on mount.
1712
+
useEffect( () => {
1713
+
let cancelled = false;
1714
+
intentRef.current = draftStore.consumePublishIntent();
1715
+
draftStore.load().then( ( d: WriteDraft | null ) => {
1716
+
if ( cancelled || ! d ) {
1717
+
return;
1718
+
}
1719
+
restoredRef.current = true;
1720
+
initialBlocksRef.current = d.blocks;
1721
+
setTitle( d.title );
1722
+
setLede( d.lede );
1723
+
setBlocks( d.blocks );
1724
+
if ( d.coverDataUrl ) {
1725
+
setCover( {
1726
+
ref: { $type: 'blob', ref: { $link: '' }, mimeType: '', size: 0 },
1727
+
previewUrl: d.coverDataUrl,
1728
+
} );
1729
+
}
1730
+
setEditorKey( ( k ) => k + 1 );
1731
+
} );
1732
+
return () => {
1733
+
cancelled = true;
1734
+
};
1735
+
}, [ draftStore ] );
1736
+
1737
+
// Load publications once signed in.
1738
+
useEffect( () => {
1739
+
if ( ! agent || ! did ) {
1740
+
return;
1741
+
}
1742
+
let cancelled = false;
1743
+
listPublications( agent, did )
1744
+
.then( ( list ) => ! cancelled && setPublications( list ) )
1745
+
.catch( () => ! cancelled && setPublications( [] ) );
1746
+
return () => {
1747
+
cancelled = true;
1748
+
};
1749
+
}, [ agent, did ] );
1750
+
1751
+
// Resume: a publish intent + a signed-in session auto-opens the publish flow.
1752
+
useEffect( () => {
1753
+
if ( status === 'signed-in' && intentRef.current ) {
1754
+
intentRef.current = false;
1755
+
setFlowOpen( true );
1756
+
}
1757
+
}, [ status ] );
1758
+
1759
+
const reloadPublications = () => {
1760
+
if ( agent && did ) {
1761
+
listPublications( agent, did )
1762
+
.then( setPublications )
1763
+
.catch( () => setPublications( [] ) );
1764
+
}
1765
+
};
1766
+
1767
+
async function persistDraft() {
1768
+
await draftStore.save( {
1769
+
title,
1770
+
lede,
1771
+
blocks,
1772
+
coverDataUrl: cover?.previewUrl ?? null,
1773
+
} );
1774
+
}
1775
+
1776
+
async function onSignIn( value: string ) {
1777
+
await persistDraft();
1778
+
if ( pendingPublish ) {
1779
+
draftStore.setPublishIntent();
1780
+
}
1781
+
await signIn( value ); // full-page redirect; never resolves
1782
+
}
1783
+
1784
+
function onPublishClicked() {
1785
+
if ( status === 'signed-in' ) {
1786
+
void persistDraft();
1787
+
setFlowOpen( true );
1788
+
return;
1789
+
}
1790
+
// Signed out → reveal the sign-in panel framed around publishing.
1791
+
setPendingPublish( true );
1792
+
setSigninOpen( true );
1793
+
}
1794
+
1795
+
async function uploadCover( file: File ): Promise< CoverUpload > {
1796
+
const message = validateCoverFile( file );
1797
+
if ( message ) {
1798
+
throw new Error( message );
1799
+
}
1800
+
const previewUrl = await readAsDataUrl( file );
1801
+
return { ref: deferredCoverRef( file ), previewUrl };
1802
+
}
1803
+
1804
+
const canPublish = title.trim().length > 0 && blocks.length > 0;
1805
+
const signedIn = status === 'signed-in' && agent && did;
1806
+
1807
+
return (
1808
+
<>
1809
+
<AppBar current="editor" />
1810
+
1811
+
<div className="write-corner">
1812
+
{ signedIn ? (
1813
+
<AccountPill
1814
+
displayName={ displayName ? displayNameFor( { did: did!, handle, displayName, avatar } ) : ( handle ?? did! ) }
1815
+
handle={ handle }
1816
+
avatar={ avatar }
1817
+
onSignOut={ () => void signOut() }
1818
+
/>
1819
+
) : (
1820
+
<button
1821
+
type="button"
1822
+
className="write-corner__signin"
1823
+
onClick={ () => {
1824
+
setPendingPublish( false );
1825
+
setSigninOpen( true );
1826
+
} }
1827
+
>
1828
+
Sign in
1829
+
</button>
1830
+
) }
1831
+
</div>
1832
+
1833
+
{ published && <PublishedPill url={ published.url } isEditing={ false } /> }
1834
+
1835
+
{ ! signedIn && signinOpen && (
1836
+
<div className="write-signin">
1837
+
<SignInPanel
1838
+
forPublish={ pendingPublish }
1839
+
error={ error }
1840
+
onSubmit={ ( value ) => void onSignIn( value ) }
1841
+
onCancel={ () => setSigninOpen( false ) }
1842
+
/>
1843
+
</div>
1844
+
) }
1845
+
1846
+
{ signedIn && flowOpen && (
1847
+
<WritePublishFlow
1848
+
agent={ agent! }
1849
+
identity={ { did: did!, handle } }
1850
+
pdsUrl={ pdsUrl ?? '' }
1851
+
blocks={ blocks }
1852
+
coverDataUrl={ cover?.previewUrl ?? null }
1853
+
title={ title }
1854
+
description={ lede }
1855
+
publications={ publications }
1856
+
onReloadPublications={ reloadPublications }
1857
+
onPublished={ ( result ) => {
1858
+
setFlowOpen( false );
1859
+
setPublished( { url: result.articleUrl } );
1860
+
void draftStore.clear();
1861
+
// Reset to a fresh new article.
1862
+
setTitle( '' );
1863
+
setLede( '' );
1864
+
setBlocks( [] );
1865
+
setCover( null );
1866
+
initialBlocksRef.current = [];
1867
+
setEditorKey( ( k ) => k + 1 );
1868
+
} }
1869
+
onCancel={ () => setFlowOpen( false ) }
1870
+
/>
1871
+
) }
1872
+
1873
+
<div key={ editorKey }>
1874
+
<div className="write-header">
1875
+
<textarea
1876
+
className="studio__title"
1877
+
rows={ 1 }
1878
+
placeholder="Add title"
1879
+
aria-label="Article title"
1880
+
value={ title }
1881
+
onKeyDown={ ( event ) => event.key === 'Enter' && event.preventDefault() }
1882
+
onChange={ ( event ) => {
1883
+
setPublished( null );
1884
+
setTitle( event.target.value );
1885
+
} }
1886
+
/>
1887
+
<button
1888
+
type="button"
1889
+
className="write-publish"
1890
+
disabled={ ! canPublish }
1891
+
onClick={ onPublishClicked }
1892
+
>
1893
+
Publish…
1894
+
</button>
1895
+
</div>
1896
+
<textarea
1897
+
className="studio__lede"
1898
+
rows={ 1 }
1899
+
maxLength={ 3000 }
1900
+
placeholder="Add a subtitle…"
1901
+
aria-label="Subtitle"
1902
+
value={ lede }
1903
+
onChange={ ( event ) => setLede( event.target.value ) }
1904
+
/>
1905
+
<SkyEditor
1906
+
onChange={ ( instances: BlockInstance[] ) => setBlocks( normalizeBlocks( instances ) ) }
1907
+
mediaUpload={ mediaUpload }
1908
+
initialBlocks={ initialBlocksRef.current }
1909
+
/>
1910
+
<CoverImagePicker cover={ cover } onUpload={ uploadCover } onChange={ setCover } />
1911
+
</div>
1912
+
</>
1913
+
);
1914
+
}
1915
+
1916
+
/** The writing-first island: editor for every auth status, publish deferred (design 2026-06-17). */
1917
+
export default function WriteStudio() {
1918
+
return (
1919
+
<AuthProvider>
1920
+
<WriteSurface />
1921
+
</AuthProvider>
1922
+
);
1923
+
}
1924
+
```
1925
+
1926
+
- [ ] **Step 4: Run test to verify it passes**
1927
+
1928
+
Run: `npx vitest run src/components/WriteStudio.test.tsx`
1929
+
Expected: PASS (all three).
1930
+
1931
+
- [ ] **Step 5: Commit**
1932
+
1933
+
```bash
1934
+
git add src/components/WriteStudio.tsx src/components/WriteStudio.test.tsx
1935
+
git commit --no-gpg-sign -m "Add WriteStudio island: editor-first, publish deferred"
1936
+
```
1937
+
1938
+
---
1939
+
1940
+
### Task 9: `/write` route + styles + meta test
1941
+
1942
+
Mount the island at `/write` (parallel to `/editor`, both untouched) and add its chrome styles. The colocated test is underscore-prefixed per the router constraint.
1943
+
1944
+
**Files:**
1945
+
- Create: `src/pages/write.astro`
1946
+
- Create: `src/styles/write-chrome.css`
1947
+
- Test: `src/pages/_write.meta.test.ts`
1948
+
1949
+
**Interfaces:**
1950
+
- Consumes: `WriteStudio` default export; `Base` layout; `LoadingScene`; the shared editor stylesheets.
1951
+
- Produces: a static route at `/write`.
1952
+
1953
+
- [ ] **Step 1: Write the failing test**
1954
+
1955
+
```ts
1956
+
// src/pages/_write.meta.test.ts
1957
+
import { describe, it, expect } from 'vitest';
1958
+
import { readFileSync } from 'node:fs';
1959
+
1960
+
const src = readFileSync( new URL( './write.astro', import.meta.url ), 'utf8' );
1961
+
1962
+
describe( '/write route', () => {
1963
+
it( 'mounts WriteStudio as a client:only island', () => {
1964
+
expect( src ).toContain( "import WriteStudio from '../components/WriteStudio.tsx'" );
1965
+
expect( src ).toMatch( /<WriteStudio\s+client:only="react"/ );
1966
+
} );
1967
+
1968
+
it( 'ships a writing-focused title and the write chrome styles', () => {
1969
+
expect( src ).toMatch( /<Base title="Write[^"]*"/ );
1970
+
expect( src ).toContain( "import '../styles/write-chrome.css'" );
1971
+
} );
1972
+
} );
1973
+
```
1974
+
1975
+
- [ ] **Step 2: Run test to verify it fails**
1976
+
1977
+
Run: `npx vitest run src/pages/_write.meta.test.ts`
1978
+
Expected: FAIL — `write.astro` does not exist.
1979
+
1980
+
- [ ] **Step 3: Write the route + styles**
1981
+
1982
+
```astro
1983
+
---
1984
+
// src/pages/write.astro
1985
+
import Base from '../layouts/Base.astro';
1986
+
import WriteStudio from '../components/WriteStudio.tsx';
1987
+
import LoadingScene from '../components/LoadingScene.astro';
1988
+
// The island is `client:only`, so Astro's scoped styles never reach its DOM — its
1989
+
// chrome is styled globally from these shared stylesheets plus the write-specific one.
1990
+
import '../styles/app-bar.css';
1991
+
import '../styles/editor-chrome.css';
1992
+
import '../styles/login.css';
1993
+
import '../styles/write-chrome.css';
1994
+
---
1995
+
1996
+
<Base title="Write — SkyPress">
1997
+
<main class="editor-shell">
1998
+
<!-- client:only — auth + editor run only in the browser (Decisions 0001 & 0004).
1999
+
Unlike /editor this surface never gates on auth: you can write signed out. -->
2000
+
<WriteStudio client:only="react">
2001
+
<LoadingScene slot="fallback" variant="editor" />
2002
+
</WriteStudio>
2003
+
</main>
2004
+
</Base>
2005
+
```
2006
+
2007
+
```css
2008
+
/* src/styles/write-chrome.css
2009
+
* Chrome unique to the writing-first page (/write): the top-right corner (sign-in / pill),
2010
+
* the sign-in panel, the publish stepper, and the in-header Publish button. The editor body
2011
+
* itself reuses editor-chrome.css (.studio__title / .studio__lede / .studio__cover*).
2012
+
*/
2013
+
2014
+
.write-corner {
2015
+
display: flex;
2016
+
justify-content: flex-end;
2017
+
padding: 0.5rem 1rem;
2018
+
}
2019
+
2020
+
.write-corner__signin,
2021
+
.write-publish {
2022
+
font: inherit;
2023
+
cursor: pointer;
2024
+
border-radius: 999px;
2025
+
border: 1px solid currentColor;
2026
+
padding: 0.35rem 0.9rem;
2027
+
background: transparent;
2028
+
}
2029
+
2030
+
.write-publish[disabled] {
2031
+
opacity: 0.5;
2032
+
cursor: default;
2033
+
}
2034
+
2035
+
.write-header {
2036
+
display: flex;
2037
+
align-items: flex-start;
2038
+
gap: 0.75rem;
2039
+
}
2040
+
2041
+
.write-header .studio__title {
2042
+
flex: 1 1 auto;
2043
+
}
2044
+
2045
+
.account-pill {
2046
+
position: relative;
2047
+
}
2048
+
2049
+
.account-pill__trigger {
2050
+
display: inline-flex;
2051
+
align-items: center;
2052
+
gap: 0.5rem;
2053
+
background: transparent;
2054
+
border: 0;
2055
+
cursor: pointer;
2056
+
font: inherit;
2057
+
}
2058
+
2059
+
.account-pill__avatar {
2060
+
border-radius: 999px;
2061
+
}
2062
+
2063
+
.account-pill__avatar--fallback {
2064
+
display: inline-grid;
2065
+
place-items: center;
2066
+
width: 28px;
2067
+
height: 28px;
2068
+
border-radius: 999px;
2069
+
background: rgba( 0, 0, 0, 0.1 );
2070
+
}
2071
+
2072
+
.account-pill__menu {
2073
+
position: absolute;
2074
+
right: 0;
2075
+
margin-top: 0.4rem;
2076
+
min-width: 12rem;
2077
+
display: flex;
2078
+
flex-direction: column;
2079
+
background: Canvas;
2080
+
border: 1px solid rgba( 0, 0, 0, 0.15 );
2081
+
border-radius: 0.5rem;
2082
+
box-shadow: 0 8px 24px rgba( 0, 0, 0, 0.12 );
2083
+
overflow: hidden;
2084
+
}
2085
+
2086
+
.account-pill__item {
2087
+
padding: 0.6rem 0.9rem;
2088
+
text-align: left;
2089
+
background: transparent;
2090
+
border: 0;
2091
+
font: inherit;
2092
+
cursor: pointer;
2093
+
color: inherit;
2094
+
text-decoration: none;
2095
+
}
2096
+
2097
+
.account-pill__item:hover {
2098
+
background: rgba( 0, 0, 0, 0.06 );
2099
+
}
2100
+
2101
+
.write-signin,
2102
+
.writeflow {
2103
+
max-width: 32rem;
2104
+
margin: 1rem auto;
2105
+
padding: 1rem 1.25rem;
2106
+
border: 1px solid rgba( 0, 0, 0, 0.15 );
2107
+
border-radius: 0.75rem;
2108
+
}
2109
+
2110
+
.signin-panel__actions,
2111
+
.writeflow__actions {
2112
+
display: flex;
2113
+
gap: 0.75rem;
2114
+
margin-top: 0.75rem;
2115
+
}
2116
+
2117
+
.writeflow__warning {
2118
+
font-size: 0.95rem;
2119
+
}
2120
+
2121
+
.writeflow__count,
2122
+
.writeflow__error,
2123
+
.signin-panel__error {
2124
+
color: #b3261e;
2125
+
}
2126
+
```
2127
+
2128
+
- [ ] **Step 4: Run test + a full check to verify it passes**
2129
+
2130
+
Run: `npx vitest run src/pages/_write.meta.test.ts`
2131
+
Expected: PASS.
2132
+
2133
+
Run: `npm run check`
2134
+
Expected: no new TypeScript/Astro errors from the added files.
2135
+
2136
+
- [ ] **Step 5: Commit**
2137
+
2138
+
```bash
2139
+
git add src/pages/write.astro src/pages/_write.meta.test.ts src/styles/write-chrome.css
2140
+
git commit --no-gpg-sign -m "Add /write route and writing-first chrome styles"
2141
+
```
2142
+
2143
+
---
2144
+
2145
+
### Task 10: Decision record + full verification
2146
+
2147
+
Capture the durable rationale and verify the whole suite + build.
2148
+
2149
+
**Files:**
2150
+
- Create: `docs/decisions/0020-writing-first-deferred-publish.md`
2151
+
2152
+
**Interfaces:** none (docs + verification).
2153
+
2154
+
- [ ] **Step 1: Write the decision record**
2155
+
2156
+
```markdown
2157
+
<!-- docs/decisions/0020-writing-first-deferred-publish.md -->
2158
+
# 0020 — Writing-first flow: deferred publish, no remote account creation
2159
+
2160
+
## Context
2161
+
`/editor` gates the entire editor behind OAuth. We wanted a parallel surface where writing is
2162
+
the first action and auth/publication selection are deferred to publish time.
2163
+
2164
+
## Decision
2165
+
- Add a parallel route `/write` mounting a new `WriteStudio` island that renders the editor for
2166
+
every auth status (no login gate). `/`, `/editor`, `/dashboard` are untouched.
2167
+
- Images are held locally as `data:` URLs and uploaded to the PDS only at publish
2168
+
(`src/lib/write/upload-held.ts`), via one media path regardless of auth state.
2169
+
- The draft (title, lede, token-skeleton blocks, cover) survives the full-page OAuth redirect:
2170
+
light metadata + skeleton in `localStorage`, image bytes in IndexedDB
2171
+
(`src/lib/write/draft-store.ts` + `asset-store.ts`). A one-shot `publishIntent` flag makes the
2172
+
publish flow auto-resume on return.
2173
+
- Publish branches on publication count: one → confirm; many → pick; zero → inline create. The
2174
+
single-publication case still shows a confirm — publishing also posts to Bluesky (brief §10).
2175
+
2176
+
## Why not remote account creation
2177
+
atproto OAuth authenticates an existing account; `com.atproto.server.createAccount` lives on a
2178
+
PDS's hosted signup (invite/email gated) and is not exposed to third-party clients. Building an
2179
+
inline signup would make SkyPress a hosting/signup broker, contradicting the "never a PDS/relay"
2180
+
guardrail. The signed-out panel therefore links out to Bluesky signup and otherwise offers
2181
+
sign-in only.
2182
+
2183
+
## Consequences
2184
+
- Signed-in writers lose eager upload error feedback (errors surface at publish) — accepted for a
2185
+
single, simpler media path.
2186
+
- `data:`-URL drafts can be large; bytes go to IndexedDB to avoid the `localStorage` quota.
2187
+
```
2188
+
2189
+
- [ ] **Step 2: Run the full test suite**
2190
+
2191
+
Run: `npm test`
2192
+
Expected: PASS — all suites, including the new `src/lib/write/*` and `src/components/Write*` / `SignInPanel` / `AccountPill` tests.
2193
+
2194
+
- [ ] **Step 3: Type/Astro check**
2195
+
2196
+
Run: `npm run check`
2197
+
Expected: no errors.
2198
+
2199
+
- [ ] **Step 4: Build (prerender smoke — catches the router-executes-tests trap)**
2200
+
2201
+
Run: `npm run build`
2202
+
Expected: success; `/write` prerenders without 500s (confirms the `_write.meta.test.ts` underscore prefix is respected).
2203
+
2204
+
- [ ] **Step 5: Commit**
2205
+
2206
+
```bash
2207
+
git add docs/decisions/0020-writing-first-deferred-publish.md
2208
+
git commit --no-gpg-sign -m "Record decision 0020: writing-first deferred publish"
2209
+
```
2210
+
2211
+
---
2212
+
2213
+
## Manual verification (after the plan)
2214
+
2215
+
Run `npm run dev` and open `http://127.0.0.1:<port>/write` (127.0.0.1, not localhost — atproto loopback requirement, Decision 0004):
2216
+
2217
+
1. **Signed out, write + images:** type a title/lede, insert an image — it previews inline; nothing uploads (check Network: no `uploadBlob`).
2218
+
2. **Publish → redirect → resume:** click Publish, sign in; on return the draft (incl. the image) is restored and the publish flow opens automatically.
2219
+
3. **Branch — one pub:** with exactly one publication, confirm names it and discloses the Bluesky post; confirming uploads the image then publishes. Open the live article — the image renders from `getBlob`.
2220
+
4. **Branch — zero pubs:** with no publication, the inline create form appears; creating one proceeds to publish.
2221
+
5. **Branch — many pubs:** with 2+, a picker appears before confirm.
2222
+
6. **Already signed in:** reload `/write` while signed in — the pill shows; Publish opens the flow with no redirect.
2223
+
2224
+
## Self-Review
2225
+
2226
+
- **Spec coverage:** route & island (T8/T9) ✓; two corner states (T7/T8) ✓; draft persistence across redirect (T3/T4/T8) ✓; deferred one-path media (T1/T5/T8) ✓; publish branching one/many/zero with always-confirm + inline create (T6) ✓; resume-after-redirect via publishIntent (T4/T8) ✓; reuse vs build + untouched routes (file structure) ✓; new-doc-only (no `?edit` path in T8) ✓; no remote account creation (T7 link-out + T10 decision) ✓; testing constraints incl. underscore-prefixed page test (T9) ✓.
2227
+
- **Placeholder scan:** none — every step ships real code/commands.
2228
+
- **Type consistency:** `WriteDraft`, `AssetStore`, `AssetSkeleton`, `PreparedPublishContent`, `CoverUpload`, `BlobRefJson`, `Publication`, `Identity`, and `computePostPreview`'s input shape are used consistently across tasks; `uploadHeldAssets`/`publish`/`attachBlobRefs` signatures match their definitions in the reused modules.
2229
+
```
+153
docs/superpowers/specs/2026-06-17-writing-first-flow-design.md
+153
docs/superpowers/specs/2026-06-17-writing-first-flow-design.md
···
1
+
# Writing-first flow — design
2
+
3
+
**Date:** 2026-06-17
4
+
**Status:** Design — approved, pending spec review
5
+
**Branch:** `chicago-v2`
6
+
7
+
## Summary
8
+
9
+
An alternative entry experience for SkyPress where **writing is the first thing you do**.
10
+
Today the flow is login-first: `/` is a marketing landing page and the editor at `/editor`
11
+
gates the entire writing surface behind `status === 'signed-in'`. This design inverts that:
12
+
the writer lands directly on an editor, starts writing immediately, and only encounters
13
+
auth and publication selection at publish time.
14
+
15
+
This ships as a **parallel experience** at a new route — `/`, `/editor`, and `/dashboard`
16
+
are left untouched so the two funnels can be compared side by side.
17
+
18
+
## Goals
19
+
20
+
- A writer can land on a page and start writing with zero friction — no login gate.
21
+
- Authentication is deferred to publish time and resumes the publish flow automatically
22
+
after the OAuth redirect round-trip.
23
+
- Image insertion works while signed out; uploads are deferred to publish.
24
+
- Publishing branches sensibly on how many publications the writer owns (one / many / zero).
25
+
- A returning, already-signed-in writer gets a small account pill but the editor stays the
26
+
focus.
27
+
28
+
## Non-goals
29
+
30
+
- **Not** a replacement for the current landing page or `/editor`. This is option B
31
+
(parallel route), explicitly for comparison.
32
+
- **No remote account creation.** atproto OAuth is a sign-in protocol; a third-party client
33
+
cannot create accounts on a big PDS, and SkyPress must never become a PDS/signup broker
34
+
(product guardrail). We surface only a lightweight "Need an account? →" link to Bluesky's
35
+
hosted signup.
36
+
- **New-document only.** This is a "start writing" funnel. Editing an existing article stays
37
+
on `/editor` (`Studio`). No `?edit=<rkey>` load path here.
38
+
- **No inline publication management.** Creating/editing publications in general stays on the
39
+
existing `/dashboard`. The one exception is a focused inline "create your first publication"
40
+
step inside the zero-publication publish branch.
41
+
42
+
## Decisions (from brainstorming)
43
+
44
+
| # | Decision |
45
+
|---|----------|
46
+
| Q1 | Positioning: **parallel route** (`/write`), existing routes untouched. |
47
+
| Q2 | Account creation: **sign-in only** for now, with a "Need an account? →" link to Bluesky signup. No real create-account branch. |
48
+
| Q3 | Images signed-out: **insert freely, upload silently at publish** (invisible deferral). |
49
+
| Q4a | Single-publication publish: **always show a lightweight confirm** ("Publish to *Name* — also posts to Bluesky"), never silent auto-publish. |
50
+
| Q4b | Zero-publication publish: **inline create-publication step** (reuse `PublicationForm`), not a redirect to `/dashboard`. |
51
+
| Q5 | Signed-in pill: **links out to existing `/dashboard`** for management; pill itself is the only new account surface. |
52
+
| Q6 | Media: **always defer (one path)** — hold locally and upload at publish regardless of auth state. |
53
+
54
+
## User journey
55
+
56
+
### Signed-out writer
57
+
1. Lands on `/write` → clean editor (title, lede, blocks, cover). No gate.
58
+
2. Writes; inserts images (held locally, previewed inline).
59
+
3. Clicks **Publish** → draft + images persisted locally, `publishIntent` set → OAuth redirect.
60
+
4. Returns signed in → draft restored, `publishIntent` detected → publish flow auto-resumes,
61
+
branching on publication count (see below).
62
+
5. Success → draft cleared, published pill/link shown.
63
+
64
+
### Already-signed-in writer
65
+
1. Lands on `/write` → same editor, plus an **account pill** (avatar + handle) top-right.
66
+
2. Clicks **Publish** → no redirect; publish flow runs in place, same branching.
67
+
68
+
### Publish branching (after auth is guaranteed)
69
+
- **Exactly one publication** → "Publish to *Name* (also posts to Bluesky)" confirm →
70
+
upload held images → commit document + Bluesky post.
71
+
- **More than one** → publication picker step → confirm → publish.
72
+
- **Zero** → inline "create your first publication" step (`PublicationForm`) → publish.
73
+
74
+
## Architecture
75
+
76
+
### Route & island
77
+
- New page `src/pages/write.astro` mounting a client-only island **`WriteStudio`**.
78
+
- `WriteStudio` wraps `AuthProvider` (reused) but, unlike `Studio`, **renders the editor for
79
+
every auth status** (`loading` / `signed-out` / `signed-in`). There is no login gate.
80
+
- The OAuth `redirect_uri` is the current pathname (existing `oauth.ts` behavior), so a
81
+
sign-in initiated from `/write` returns to `/write` automatically. No new redirect config.
82
+
83
+
### Top-right corner states
84
+
- **Signed out:** a "Sign in" affordance + a small "Need an account? →" link to Bluesky
85
+
signup. Reuses the existing handle-input / `signIn()` path from `AuthProvider`.
86
+
- **Signed in:** the **account pill** — avatar + handle opening a menu: *Manage publications*
87
+
(→ `/dashboard`), *Profile*, *Sign out*.
88
+
89
+
### Draft persistence (survives the OAuth redirect)
90
+
Sign-in is a full-page redirect that destroys in-memory state, so before any redirect we
91
+
persist a **single draft slot**:
92
+
- **localStorage** — title, lede, serialized blocks, cover ref/preview, and a `publishIntent`
93
+
flag.
94
+
- **IndexedDB** — held image bytes (data URLs can exceed localStorage quota), keyed so blocks
95
+
can reference them on restore.
96
+
97
+
On `/write` load we **auto-restore** the draft if present. After a successful publish we
98
+
**clear** both stores. Abandoned drafts persist for the next visit.
99
+
100
+
### Deferred media (one path)
101
+
A new **local-hold media handler** replaces the eager PDS-upload handler for this flow, used
102
+
regardless of auth state:
103
+
- On insert: store image bytes in IndexedDB, render an inline preview (data URL), and record
104
+
the mapping (preview → held key) in the in-memory blob registry.
105
+
- At publish: for every held image, `agent.uploadBlob()` → real `BlobRef`, then reuse the
106
+
existing `attachBlobRefs()` registry mechanism to swap preview URLs for blob refs before the
107
+
document record commits.
108
+
- Errors surface at publish (acceptable trade-off vs. eager-upload early feedback).
109
+
110
+
### Publish-flow stepper
111
+
A small state machine driven by `publishIntent` + publication count:
112
+
- `idle` → (Publish clicked) → persist + maybe-redirect → `resolving-auth`
113
+
- `resolving-auth` → (signed in) → `branch`
114
+
- `branch` → one of `confirm-single` / `pick` / `create-pub`
115
+
- any terminal step → upload images → `publish()` (document + post) → `done` (clear draft).
116
+
117
+
Reuses `publisher.ts` (`publish`), `publications.ts` (`listPublications`, `createPublication`),
118
+
`PublicationForm`, and the published-pill UI.
119
+
120
+
## Reuse vs. build
121
+
122
+
**Reuse (unchanged):** `AuthProvider`, `oauth.ts`, `SkyEditor`, `PublicationForm`,
123
+
`publisher.ts` (`publish`), `publications.ts`, `attachBlobRefs`, published-pill UI.
124
+
125
+
**Build new:**
126
+
- `src/pages/write.astro` route.
127
+
- `WriteStudio` island (editor for all auth states; corner state; publish stepper host).
128
+
- Local-hold media handler.
129
+
- Draft-persistence module (localStorage + IndexedDB; save / restore / clear).
130
+
- Account pill / signed-out corner component.
131
+
- Publish-flow stepper component (confirm / pick / create-pub) driven by `publishIntent`.
132
+
133
+
**Untouched:** `/` (`index.astro`), `/editor` (`Studio`), `/dashboard`.
134
+
135
+
## Testing
136
+
137
+
- Colocated page tests under `src/pages/` MUST be underscore-prefixed (e.g.
138
+
`_write.meta.test.ts`) per the Astro file-router constraint.
139
+
- Draft persistence: save → simulate reload → restore yields identical editor state
140
+
(title/lede/blocks/cover); clear empties both stores.
141
+
- Deferred media: held images survive a persist/restore round-trip; at publish each held
142
+
image is uploaded once and its preview URL is swapped for the blob ref before commit.
143
+
- Publish branching: one / many / zero publications each route to the correct step; the
144
+
single-publication case still shows a confirm (never silent).
145
+
- Resume-after-redirect: a `publishIntent` present on load auto-resumes the publish flow
146
+
rather than dropping into the editor.
147
+
- `WriteStudio` renders the editor for `loading`, `signed-out`, and `signed-in` (no gate).
148
+
149
+
## Open questions
150
+
151
+
None outstanding. Durable rationale (e.g. the deferred-media single-path choice and the
152
+
no-remote-account-creation constraint) should graduate to a `docs/decisions/NNNN-*.md` during
153
+
implementation.