Skip to content

fix(library): dim artifact-table writes while the gateway is offline - #20989

Merged
chenmingwei23 merged 2 commits into
mainfrom
replace/10832
Oct 16, 2026
Merged

chenmingwei23 merged 2 commits into
mainfrom
replace/10832

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: While the gateway is offline, the artifacts library table shows its writes (row star, row Delete, folder Rename / Move / Color / Delete) as unavailable and says why, instead of looking live and then failing.

With the gateway offline, every write control in the library table stays at full weight. Clicking a row's star fires PATCH /api/artifacts/<slug>/pin, the request cannot land, and the page shows a red "Failed to fetch" banner. The folder ⋯ menu's Rename, Move to folder, Color swatches and Delete look equally clickable. The chat sidebar beside it already dims these writes and shows a reason row (#20749), so one dashboard teaches two rules.

Why it matters

A user who learned that a dimmed sidebar row means "not now" has no reason to read a full-weight star or Delete as unavailable, so the only way to find out is to click it and meet an error that reads like a server failure. A folder rename typed while the gateway drops is committed into a write that cannot land, and the typed name is lost with the closed field.

Not a goal

What changed (motivation → approach → change)

Symptom: library writes stay live offline and fail with "Failed to fetch". Root cause: LibraryTable.tsx never reads the connection flag. Rule applied (same as #20749): gate the write at its sink, dim its entry control, and give the reason a visible channel.

  • Folder ⋯ menu (FolderMenu): Rename and Delete use offlineMenuRow (dim, offline tooltip and accessible name, refused onSelect keeps the menu open); Move to folder passes FolderMoveSubmenu's offline / offlineTitle and the pick is refused at this caller; the colour swatch strip dims once and its buttons are disabled; OfflineMenuReason renders last.
  • Rows: ArtifactRow's star and Delete and SessionDocStar dim, carry offlineProps, and return before the write. The click still stops propagation so a refused click does not open the artifact.
  • Table reason row: LibraryTable and LibraryTree render a sticky reason row after the table (a coarse pointer opens no tooltip). It is OfflineReasonRow, a named export beside OfflineMenuReason in components/OfflineMenuReason.tsx, reusing utils.offline.menu_reason.
  • Held rename: FolderNameInput refuses its blur commit offline, so the editor and its draft stay mounted, and shows a note (linked by aria-describedby) that closing the field discards the name.
  • Strings: four utils.offline keys (star_artifacts, delete_artifacts, save_folder_names, name_not_saved_keep_field_open) in en.manual.json and the 12 locale catalogues. ja/ru style tests guard the {{action}} grammar of these verbs.

Ported from #10832 onto main after #20749: the fork's own dimmed prop, OfflineReasonRow.tsx and offlineVerb (cannot-expand) submenu are dropped in favour of the primitive main now carries.

Backwards compatibility

Compatible: all changes are optional props or offline-only branches; online behaviour of every control is unchanged.

Removes nothing: offline the dimmed controls refuse a write that already could not reach the gateway; no data, key, route or public function is removed.

Tests

  • LibraryTable.folderMenuOffline.test.tsx (new): folder-menu rows are aria-disabled, dimmed (Delete drops its red), fire no write and keep the menu open; the Move trigger is dimmed with its tooltip and a pick from it writes nothing; swatches dim once and fire no write; row star / Delete and the session-doc star refuse with one dim layer and a tooltip; the table and tree render the reason row last; FolderNameInput holds an offline draft, abandons an empty one, and lets Escape out. Each case has a connected control asserting the write still happens.
  • ArtifactsPage.test.tsx, ArtifactsPageCoverage.test.tsx: suites that assert a write reaches the server now seed a connected gateway.
  • jaStyle.test.ts, ruStyle.test.ts: utils.offline action verbs must fit the {{action}} frame (ja: no の-nominalisation without を; ru: infinitive).

Local: tsc -p tsconfig.app.json clean; ESLint clean on touched files; 125 vitest files / 1,905 tests pass across src/components, src/test/ArtifactsPage*, src/test/FolderMoveSubmenu* and the sidebar offline suites; i18n-check.mjs, check-i18n-keys, check-i18n-strings, restyle ratchet, phantom-classes, theme-colors, ui-index check and the feature-map gate pass.

Manual verification

Built SPA (main and this branch) served with stubbed /api/**; the /api/ws stub closes the socket (offline) or keeps it open (online). Offline on main, clicking an unstarred row's star sent PATCH /api/artifacts/cr-queue/pin and showed "Failed to fetch"; on this branch it sent nothing. Online on this branch the same click sent the PATCH. A folder rename committed after the socket dropped sent PATCH /api/artifact-folders/fa on main and closed the field; on this branch it sent nothing and kept the draft.

Screenshots / video

Table, offline, after clicking a row star — before (main) / after:

Library table offline on main: full-weight controls, Failed to fetch after a star click
Library table offline after: star and Delete dimmed, no request, reason row under the table

Folder ⋯ menu, offline — before (main) / after:

Folder menu offline on main: every row full weight
Folder menu offline after: Rename, Move, colours and Delete dimmed, reason row last

Folder rename while the gateway drops mid-edit (opened online, typed "Quarterly reports", gateway dropped, Enter) — before (main) / after:

Rename on main: the PATCH is sent into a dead gateway and the field closes; the typed name is gone
Rename after: no request, the editor keeps "Quarterly reports" with a visible note that the name is not saved

Session document ("From your chats") star, offline — before (main) / after:

Session-doc star offline on main: full weight
Session-doc star offline after: dimmed, reason row under the table

Online after (unchanged controls)

Library table online after
Folder menu online after

Related Issues

Fixes #20988
Replaces #10832 — thanks @rnoack1, whose change this is; the commit keeps their authorship. Builds on the offline primitive from #20749.

Pattern harvest

Rule candidate: review-prompt
Pattern: a dashboard control that writes to the gateway (api.* mutation in an onClick/onSelect) with no useConnected gate at the sink or offline dim on the control.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.

Star, Delete and the folder menu wrote through the gateway with no connected
check, so an offline click looked like it worked. Split from a larger sweep.

Ported onto the offline primitive #20749 landed: menu rows use offlineMenuRow
and the `offline` dim on DropdownMenuItem, the Move submenu uses
FolderMoveSubmenu's offline/offlineTitle with the pick refused at the caller,
the menu reason is OfflineMenuReason, and the table/field reason row is a named
OfflineReasonRow beside it reusing utils.offline.menu_reason.

Co-authored-by: Joe Guo <12429733+iamwhatever@users.noreply.github.com>
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 15, 2026
@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 65b3ed2d4116d6a08b1fc2015c5143130d2f45fa — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Check the new-folder inputs and the gallery rename card: FolderNameInput now holds offline drafts there too, though the description says gallery is out of scope.

[DESIGN-REVIEWED] 65b3ed2

Description read

[DESCRIPTION-READ] efb42204ae3006387dc5491661bbcf6a2e135bba472fdad59c67a3036c528283

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — 🟡 CONCERNS

Premise-level review of 65b3ed2d4116d6a08b1fc2015c5143130d2f45fa — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: CONCERNS

Dragging an artifact onto a folder is still an ungated write offline, while the new table reason row tells the user that writes need a connection.

Not justified as shipped

  • Item 1 — symptom-level: the stated root cause is "LibraryTable.tsx never reads the connection flag", but the same gap remains at ArtifactsPage.tsx:460 handleDragEnd → armArtifactMove. That is 1 unfixed sibling write on this table, found by grepping useConnected|setArtifactFolder|onDragEnd in ArtifactsPage.tsx: 0 useConnected hits. ## Not a goal does not exclude drag.
    Clears when: the description says drag-to-folder is left unfixed and why, or a human accepts the deferral.
  • Item 6 — undeclared: FolderNameInput is shared, so the offline hold also covers folder create (the new ArtifactsPageCoverage test "offline the create is refused…") and the gallery's name field. The description only mentions "Held rename".

What this change ships

Inventory (8 items) — 6 justified

Intent: let a user see, while the gateway is offline, which library-table writes are unavailable and why, instead of hitting "Failed to fetch". FIX.

  1. Offline, the row star and row Delete are dimmed, show a tooltip and send nothing — symptom-level: drag-to-folder is still ungated
  2. Offline, the session-document star is dimmed and refuses the click — justified
  3. Offline, folder-menu Rename and Delete are dimmed and the menu stays open — justified
  4. Offline, the Move-to-folder trigger is dimmed and a pick from it is refused — justified
  5. Offline, the colour swatch strip is dimmed and its swatches are disabled — justified
  6. Offline, a typed folder name is held with a note instead of being lost — undeclared: also covers create and the gallery field
  7. A sticky reason row now sits under the flat table and the folder tree — justified
  8. New OfflineReasonRow export and four utils.offline strings across all locales — justified

[FIRST-PRINCIPLES-REVIEWED] 65b3ed2

Description read

[DESCRIPTION-READ] 9e52fbc684265648dfc6d6d698149292e88b1774da0fa8d72615d8d639e2a38b

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — 🟡 CONCERNS

UX-level review of 65b3ed2d4116d6a08b1fc2015c5143130d2f45fa — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

UX-Verdict: CONCERNS

Offline, an unstarred row's star looks exactly as it does online, so the most common write this PR gates still looks live.

Watch

  • The unstarred star doesn't look dimmed. Online the empty star is text-muted/40. Offline it is text-muted plus opacity-40, which renders at about the same strength. Only the cursor changes, so there's no visual cue. The blind reader on shot-02: "The empty stars don't look any different, so I can't tell." On shot-08 they read the offline state only from the faded ×. Most rows are unstarred and this is the first write the PR's goal names, so the user meets it every offline visit. Smallest fix: give the offline unstarred star a visibly different look, for example a dimmer alpha.
  • The held-rename note asks the user to do something they can't. The note reads "Keep this field open and reconnect" (name_not_saved_keep_field_open), but the page offers no reconnect action. The blind reader on shot-06: "I don't know how to 'reconnect'… I'd be stuck with an open text box I'm afraid to close." The user ends up frozen in the field, unsure whether to act or wait. This only happens when the gateway drops mid-rename, but it costs the user a lot when it does.

Suggestions

  • name_not_saved_keep_field_open: replace with "Gateway offline — not saved yet. Keep this field open; it saves when the gateway reconnects. Closing it discards the name." If the draft doesn't actually save on reconnect, the note should say what the user has to do instead, such as pressing Enter again once connected.

[UX-REVIEWED] 65b3ed2

Description read

[DESCRIPTION-READ] 537e58e0239abc06a2ef10005c0a2b8a12798c675ea269bc11bce04551c7596b

That sha256 names everything this verdict read: the PR description, plus the 13 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 65b3ed2d4116d6a08b1fc2015c5143130d2f45fa — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 65b3ed2

Verdict parsed from the review's SHA-scoped output markers for commit 65b3ed2d4116d6a08b1fc2015c5143130d2f45fa.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 65b3ed2d4116d6a08b1fc2015c5143130d2f45fa: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 65b3ed2d4116d6a08b1fc2015c5143130d2f45fa and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 65b3ed2

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 65b3ed2d4116d6a08b1fc2015c5143130d2f45fa: <one-sentence reason>

@iamwhatever
iamwhatever marked this pull request as ready for review October 16, 2026 00:15
@iamwhatever
iamwhatever requested review from a team and KiroCrewCaptain as code owners October 16, 2026 00:15
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 16, 2026

@chenmingwei23 chenmingwei23 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Approving: readiness: passed, all lanes green, no outstanding change requests.

@chenmingwei23
chenmingwei23 merged commit 864e05f into main Oct 16, 2026
106 checks passed
@chenmingwei23
chenmingwei23 deleted the replace/10832 branch October 16, 2026 01:37
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Artifacts library table writes stay live while the gateway is offline

3 participants