Repository navigation
fix(apps): show why a refused builtin page is empty, not a chat redirect - #13004
Conversation
|
Intent: A page whose registration the core refused must say why it is empty, instead of silently redirecting the user to chat. |
Design Review (Fable 5) — ✅ PASSDesign-level review of Design-Verdict: PASS Verify [DESIGN-REVIEWED] 5ecb131 |
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
First Principles Review (Fable 5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Verify the description's runtime claims the reviewer cannot: that every new test fails on base and the five named negative controls each turn one test red. What this change shipsInventory (9 items) — 9 justifiedIntent: make a refused builtin-page registration readable where the user meets it, instead of a silent chat redirect — a FIX.
Facts checked: [FIRST-PRINCIPLES-REVIEWED] 5ecb131 |
UX Review (Fable 5) — ✅ PASSUX-level review of UX-Verdict: PASS Nothing to check. [UX-REVIEWED] 5ecb131 |
Opus 5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
dafe946 to
21afa18
Compare
|
span=14476f68e3fe
|
|
span=326aeca1cd28
|
|
span=b4a2654e5344
|
|
span=621b4f938c54
|
|
span=b2342b2349e0
|
21afa18 to
d5195e0
Compare
|
span=326aeca1cd28
|
d5195e0 to
69c036f
Compare
A refused page registration was only a console.warn in a production bundle, and the route then fell through BuiltinAppRoute's miss path to /chat. A downstream edition shipped ten pages refused for a missing appId; clicking any of them landed on chat with no signal a user could see. The registry now remembers why, under the key the router will ask for, and the route renders a panel naming the page, saying in plain words that retrying cannot help, and carrying the registration diagnostic under a label for whoever assembled the build. The throw is kept so the boundary still journals to recordError and RUM; both of that component's boundaries are keyed by the resolved path, because App.tsx serves all builtin pages from one unkeyed route and without a key a single caught throw followed the user onto every builtin page they opened next. Registration still degrades safe -- throwing there would take the whole dashboard down over one bad entry.
a6f8aa7 to
5ecb131
Compare
|
span=9ab233ccef75
|
|
span=9b96a5f4ab4b
|
…ect (kirodotdev#13004) A refused page registration was only a console.warn in a production bundle, and the route then fell through BuiltinAppRoute's miss path to /chat. A downstream edition shipped ten pages refused for a missing appId; clicking any of them landed on chat with no signal a user could see. The registry now remembers why, under the key the router will ask for, and the route renders a panel naming the page, saying in plain words that retrying cannot help, and carrying the registration diagnostic under a label for whoever assembled the build. The throw is kept so the boundary still journals to recordError and RUM; both of that component's boundaries are keyed by the resolved path, because App.tsx serves all builtin pages from one unkeyed route and without a key a single caught throw followed the user onto every builtin page they opened next. Registration still degrades safe -- throwing there would take the whole dashboard down over one bad entry.
Problem / Motivation
You click a page in the sidebar and land on chat. No error, no message. The page
you asked for is simply gone.
That is what a refused page registration looks like today.
registerBuiltinComponentsrefuses an entry it cannot use — a route that can never resolve, or a missing or
malformed
appId. In dev and test it throws, so the refusal is loud. In aproduction bundle it is one
console.warn, and thenBuiltinAppRoutetreats theroute like any unknown path and redirects to
/chat.A downstream edition hit this: it registered ten builtin pages the old way, with
a bare component and no
appId. All ten were refused. All ten redirected to chat.Nobody saw a warning, because nobody has a production console open.
Why it matters
The warn-in-production policy is right, and this PR keeps it. Throwing at
registration would take the whole dashboard down over one bad page, which is worse
than the page being missing.
But degrading safe is not the same as degrading silently. A downstream edition
compiles its own bundle, so the dev/test throw never runs over its registrations.
The production warn is the only signal it ever gets, and a warn in a shipped app
reaches nobody. The result is a page that vanishes with no trace and no way for the
person looking at the empty space to find out why.
What changed (motivation → approach → change)
Symptom: a refused page is indistinguishable from a page that does not exist.
Root cause: the refusal is reported and then discarded, so by the time the user
navigates there is nothing left to read. Fix: keep the refusal, and show it where
the user meets it.
/chat/chat/chatwebsite/src/apps/seamCollision.tskeeps its two-argument shape; the record lives inwebsite/src/apps/builtinRegistry.ts, next to the miss path that reads it, becauseonly a seam with somewhere to show a refusal benefits from remembering one. A
reportRefusalhelper records then reports, making the ordering structural.The key is the one the router will ask for, not the string the entry registered: nothing
can ask for
/reports/daily, so a reason filed there is unreadable. Deriving it isdecoding, not slicing, because
%is outside the route pattern so every escaped route isrefused. It mirrors react-router's two passes — cut query and hash on a literal
?/#,decode the pathname's segments under one try/catch, then apply
matchPath's%2Fpass —so
/reports%2Ddailyis asked for as/reports-dailyand%252Fresolves to/. Aroute with no leading
/gets no key: no URL produces that spelling. A duplicate getsnone either — it still resolves to the winning entry.
website/src/apps/BuiltinAppRoute.tsxsplits the miss path in two. An unknown pathis a typo or a stale link and still goes to chat. A path whose registration was
refused renders a panel supplied as the boundary's
fallback: it names the page,says in plain words that the build has to be corrected and retrying cannot help, and
carries the registration diagnostic under a label for whoever assembled the build. It
offers the agent hand-off and no Try Again, which on a refusal could never succeed.
The throw is kept because
fallbackoverrides only what renders, socomponentDidCatchstill journals to
recordErrorand RUM. Both ofthat component's boundaries are keyed by the resolved path, because
App.tsxservesevery builtin page from one unkeyed
<Route path="/:builtinApp/*">: abuiltin-to-builtin move is a param change on a mounted component, and
ErrorBoundaryreturns its fallback before it reads
childrenwith no reset on a prop change. Withoutthe key, one caught throw followed the user onto every builtin page they opened next
until a reload. Keying by the resolved segment rather than the full URL is what keeps
an app's own sub-path navigation from remounting the page on every step.
Its three strings are new
apps.builtinAppRoutekeys, translated in every catalogueunder
website/src/i18n/locales/with notes inwebsite/src/i18n/en.context.json;en-XA.jsonis regenerated.website/docs/extension-seams.md, wherewebsite/AGENTS.mdroutes seam work, said anon-conforming route redirects to chat. It now states that remembering a refusal
belongs to the seam with somewhere to show it, how the key is derived, and why the
refused page drops Try Again while keeping the throw.
Not a product-shape change: behaviour differs only on a refused route or a crashed
page, both defect states.
Backwards compatibility
Compatible:
reportSeamCollisionkeeps its two-argument signature, so all ~23existing calls are untouched and the throw/warn policy is unchanged; the refusal
record lives in
builtinRegistry.ts, the one seam with a surface to show it on. In thisrepository's own builds no registration is ever refused — the core table is
compile-time code held to
isValidAppIdbybuiltinRegistry.identity.test.tsx— sono route reachable in a stock build changes. The
keyadded to the entry branch'sboundary remounts a page only on a route change, which already unmounted it.
Tests
website/src/test/builtinRegistry.refusalVisible.test.tsx, 25 cases, stubbingimport.meta.env.DEVto false because production is the only build where a refusalsurvives registration:
appIdand a malformed route each record their reason, and still do not register?/#, not a decoded oneNavigation runs through the real router via a
useNavigateharness inside oneMemoryRouter; a mocked navigate or changedinitialEntrieswould not reproduce theparam-change condition the boundary defect needs, and five of the decoding cases
assert end-to-end through the router rather than through
seamRefusalReason. Everynew case was verified failing against the pre-fix code. Five negative controls each
turn exactly one test red: removing the entry branch's key, dropping the
%2Fpass,decoding per segment instead of per pathname, cutting the query after decoding, and
reverting the
fallbackprop.website/src/test/BuiltinAppRoute.test.tsxgains the newregistry export to its total mock, which localizing the store made incomplete.
Manual verification
Both shots come from this repo's own screenshot harness
(
website/scripts/lib/serve-dist.mjsandwebsite/scripts/lib/boot-api.mjs): itserves the real built SPA and answers every
/api/**call from the shared bootfixtures, so the shell boots without a gateway. Two production builds of this same
tree, one at this head and one at
origin/main, each composed with one throwawayedition that registers
/aimthe old way (bare component, noappId). Sameviewport both times, so the pair differs only in the branch.
Screenshots / video
Before, on
origin/main—/aimis refused and the user silently lands on chat:After, on this branch —
/aimstays put and names the reason:Related Issues
no linked issue: found while tracing why an edition's ten pages bounced to chat.
Pattern harvest
Rule candidate: review-prompt
Pattern: a refusal reported into a log and then discarded, leaving the user-facing
miss path unable to tell "never registered" from "registered and rejected".
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)