Repository navigation
Commit aec5f7b
![objectstack-fleet[bot]](https://avatars.githubusercontent.com/u/254823548?v=4&size=40){kind=avatar}
refactor(app-shell)!: retire the 54 root-entry exports that nothing outside the package names (#26219)
<!-- claude-projects-attribution: {"github_login":"os-steve"} -->
_Requested by **Steve** · [project
thread](https://claude.ai/code/project/chan_01FdL1XeUyvVNxLreh3F4Qi9?thread=cmsg_01FdL1XeUyvVNxLreh3F4Qi9WDHUTc91Ru3wKHsnWYaas9)_
Part of #25922 (step 1 only: the zero-reference exports and the
architecture guide; the package split and the designer-strings migration
stay with the card).
Clause-②: yes (narrowing) (removes published exports from
`@object-ui/app-shell`; the seat records a TIER_DEFAULT contract review
before landing)
Metadata-protocol: none
## What changes
- `ui/packages/app-shell/src/index.ts` stops publishing 54 names that no
file in this repository outside the package names. Every defining module
stays; only the root entry changes. The entry goes from 261 names to 209
(`main` added `InvitationSignUpPrompt` and `isDefaultProductName`
meanwhile). One comment count in the entry follows (`11 TYPE-ONLY
re-exports` is now 9).
- `ui/docs/app-shell-extraction-guide.md` is rewritten to describe the
package that ships: directory sizes, the groups of names the entry
publishes, its load-time registrations, its dependencies and peer
dependencies, and its three consumers here (`apps/console`,
`examples/console-starter`, `examples/byo-backend-console`). The six
compiled `tsx` usage blocks are kept byte for byte.
- `ui/packages/app-shell/src/chrome/toast-helpers.ts`: its usage
docblock imported `toastWithUndo` from `@object-ui/app-shell`, which
this change makes false; it now names the module.
- `.changeset/25922-app-shell-retire-unreferenced-exports.md`: `patch`,
a **BREAKING** banner, a FROM → TO line for every retired name and the
ADR-0087 marker (see Acceptance notes: that gate is red).
## How "zero references" was measured (main `fbb75998`)
1. Every name the root entry exports, read from `src/index.ts` with its
`as` aliases resolved: 261 names (the card counted 262 at `7981384`).
2. For each name: `git grep -l -w -F NAME -- ui packages apps
':!ui/packages/app-shell/'`. Zero files means zero references. This
counts every tracked file of every kind: code, tests, docs, changelogs,
ADRs.
3. Positive control: `SchemaRenderer` is named in 1,088 files outside
the package.
4. Result: 57 names with zero hits. Three are kept because the package's
own README imports them in its examples, and
`ui/scripts/check-readme-exports.mjs` reds when a README imports a
missing export: `SignUpOffer`, `RuntimeBranding`, `studioOrgScopePath`.
The other 54 are retired.
5. Over the whole tree instead of `ui/ packages/ apps/` the count is 56:
`AssistantEditorContext` is also named in
`docs/adr/0037-live-canvas-draft-preview.md`. It is retired, because the
ADR names the module path (`app-shell/src/assistant/assistantBus.ts`),
and that module still exports it.
## Removed from the root entry (54)
- `src/providers/ExpressionProvider`: `useExpressionContext`,
`ExpressionContextValue` (type)
- `src/hooks/useUrlOverlay`: `UseUrlOverlayOptions` (type),
`UrlOverlayControls` (type)
- `src/hooks/useSettleSignal`: `SettleSignalState` (type)
- `src/observability/settleSignal`: `isIdle`, `ObjectUiGlobal` (type)
- `src/hooks/useRecentItems`: `RecentItemInput` (type), `RecentTextItem`
(type)
- `src/hooks/useRecentItemLabel`: `RecentItemLabelResolver` (type)
- `src/utils/index`: `isOverrideOnlyViewer`, `actionAdmittedByOverride`,
`bypassedApproverNames`, `DeclaredHomeApp` (type)
- `src/hooks/useAiSurface`: `AiSurfaceState` (type)
- `src/layout/index`: `PreviewBadgeProps` (type)
- `src/chrome/index`: `RedirectWithSplashProps` (type), `toastWithUndo`,
`ToastWithUndoOptions` (type)
- `src/runtime-config`: `getCloudBase`, `getBrandColor`,
`isRuntimeConfigInitialised`, `RuntimeFeatures` (type)
- `src/views/index`: `RecordFormPageProps` (type),
`DeclaredActionsBarProps` (type)
- `src/hooks/index`: `addNavigationItem`, `removeNavigationItems`,
`renameNavigationItems`, `navigationEqual`, `generateNavId`
- `src/context/index`: `CommandPaletteContextValue` (type)
- `src/console/auth/signUpOffer`: `SignUpOfferContext` (type)
- `src/hooks/useChatConversation`: `HydratedUIMessage` (type)
- `src/services/componentRegistry`: `listAppComponents`,
`urlSegmentsToComponentRef`, `AppComponentRegistryEntry` (type)
- `src/views/metadata-admin/PageShell`: `MetadataPageShell` (alias of
`PageShell`)
- `src/views/metadata-admin/registry`: `listMetadataResources`
- `src/views/metadata-admin/useMetadata`: `useMetadataTypes`,
`useTypesIndex`, `matchesQuery`
- `src/views/metadata-admin/preview-registry`: `MetadataPreviewProps`
(type)
- `src/views/metadata-admin/inspector-registry`:
`MetadataInspectorProps` (type)
- `src/views/studio-design/StudioDesignSurface`:
`StudioDesignSurfaceProps` (type)
- `src/views/studio-design/studio-canvas-preview`:
`getStudioCanvasPreview`, `listStudioCanvasPreviewTypes`,
`StudioObjectRecordsCanvas`, `StudioCanvasPreview` (type),
`StudioCanvasPreviewProps` (type)
- `src/assistant/assistantBus`: `useAssistant`,
`useRegisterAssistantEditor`, `requestAssistantOpen`,
`AssistantEditorContext` (type), `AssistantEditorField` (type)
## Tests
**Final head `41109b83`** (merge of `main` `46255b19`, which includes
the gate fix #26319; no conflicts). On it: Console build 71/71 (VERDICT
command-exit 0, tree clean); the full dogfood battery, closure 67/67
then 297 files passed / 3 skipped, 2527 tests passed / 18 skipped
(VERDICT command-exit 0); CI `Test UI` 1–16/16, Type Check UI, Lint UI,
Build & E2E UI and Check Changeset all success. None of the 54 names
gained an outside reference on the new `main` (re-measured).
Earlier runs, on head `5bf229f6`:
- `pnpm exec turbo run build --filter='@object-ui/app-shell^...'
--concurrency=2`: 64/64 tasks, lock VERDICT command-exit 0.
- `pnpm --filter @object-ui/app-shell build && pnpm --filter
@object-ui/app-shell type-check` (both `tsc --noEmit` and `tsc -p
tsconfig.test.json`): VERDICT command-exit 0, 0 `error TS`.
`dist/index.d.ts` no longer names `toastWithUndo` or `useAssistant`.
- Narrowed vitest run: 14 app-shell test files that import or read the
root entry (found by grepping the package's tests for the root `index`
specifier and for `src/index.ts`), plus
`product-neutral-renderer.ratchet.test.ts`: 14 files, 86 tests passed.
`spec-symbol-parity.test.ts` and the console's
`createdRecordPath.test.ts`, which reads `app-shell/src/index`: 2 files,
57 tests passed. The full app-shell suite is left to CI `Test UI`.
- The migration lines were compiled. A scratch `.ts` imports from the
built `dist/index.d.ts` and asserts that each of the 22 FROM → TO
derivations in the changeset is a real type, not `any` and not `never`:
`tsc` exit 0. The control file imports `toastWithUndo` and
`SettleSignalState` and fails with `TS2305 ... has no exported member`
twice, as the changeset says an importer will.
- `pnpm exec turbo run build --filter=@object-ui/console
--concurrency=2`: 71/71 tasks, VERDICT command-exit 0. The tree was
clean afterwards, so the sdui record did not move (app-shell is outside
the record).
## Gates
- `node scripts/pm/dispatch-gates.mjs --commands --repo
objectstack-ai/objectstack` on `41109b83`: 29 commands, all exit 0,
including `node scripts/check-adr-0087-registration.mjs --base
origin/main` (`runtime-export-retired` verified for all 54 operands,
after #26319). `--ran`: 29 run, 0 NOT MEASURED.
- `node scripts/check-platform-checklist.mjs --changed-from
origin/main`: exit 0 (0 anchored files in the change set).
- `ui/scripts/check-doc-links.mjs`: exit 0. The links in the rewritten
guide resolve.
- `ui/scripts/check-readme-exports.mjs`: exit 1, but only on 72
self-imports of packages outside app-shell's build closure that this
container did not build (`cli`, `plugin-ai`, `plugin-gantt`,
`plugin-map`, …). No app-shell README line is among them. CI runs it on
a full build.
- `ui/scripts/check-doc-snippet-types.mjs`: NOT MEASURED locally,
because it needs nearly every ui package built. The guide's six `tsx`
fences are byte-identical to main (`cmp` over the extracted fences), and
the names they import (`AppShell`, `MinimalAppShellProps`) stay
exported. CI runs it.
- Full dogfood battery (owed because of the `!` in the title): measured
on the final head `41109b83`, VERDICT command-exit 0 (see Tests).
## Acceptance notes
- **ADR-0087 gate: green since #26319** (the gate now reads the ui
workspace roots and `.tsx` declarations). History: before that fix it
was red, and it was the gate's gap, not this diff's. The disposition
that fits is `not-required (runtime-export-retired
@object-ui/app-shell#NAME, ...)`. The gate refuses all 54 operands at
predicate 1 with "no workspace manifest at fbb7599 is named
`@object-ui/app-shell`": `PACKAGE_ROOTS` in
`scripts/check-adr-0087-registration.mjs` is `['packages', 'apps',
'examples']`, while `pnpm-workspace.yaml` also lists `ui/packages/*`,
`ui/apps/*` and `ui/examples/*`. A local probe that added the three
`ui/` roots (restored afterwards, `git diff HEAD` empty) took predicate
1 to green for all 54, and left 16 refused at predicate 2 ("the
declaration of NAME cannot be located at the merge base"): aliases
(`MetadataPageShell`), shim re-exports (`RecentItemInput`,
`RecentTextItem`) and `.tsx` declarations (`PreviewBadgeProps`,
`RecordFormPageProps`, `StudioDesignSurfaceProps`, …). No other
disposition fits honestly: `no-migration-prescription` would hold only
on a detector miss, because the body prescribes 54 rewrites. Fixing the
gate is outside this card's file surface; the seat decides how to route
it.
- `toastWithUndo` and `ToastWithUndoOptions` have no caller inside the
package either, so `chrome/toast-helpers.ts` is now dead code. It is
left in place, because the card retires exports, not modules.
- Some retired types describe names the entry still exports, for example
`MetadataPreviewProps` for `registerMetadataPreview` and
`StudioCanvasPreviewProps` for `registerStudioCanvasPreview`. They are
retired because the card's rule is "no caller, retire". The changeset
gives each a compiled derivation from the name that stays.
- Consumers outside this repository (cloud, hotcrm, npm) were not
measured.
- `docs/ARCHITECTURE.md` in the card does not exist on main under `ui/`.
The file the card quotes ("Minimal application rendering engine", five
exports, "~50KB") is `ui/docs/app-shell-extraction-guide.md`, which
calls itself the architecture guide. That file is the one rewritten
here, and it keeps its name because
`ui/scripts/markdown-test-inputs.mjs` and
`check-doc-snippet-types.test.ts` list it.
---
_Generated by [Claude
Code](https://claude.ai/code/session_012zuvAzwT4oemWPhAR81wRm)_
---
_Generated by [Claude Code](https://claude.ai/code)_
---------
Co-authored-by: Claude <noreply@anthropic.com>1 parent 3db7bbf commit aec5f7b
4 files changed
Lines changed: 222 additions & 226 deletions
File tree
- .changeset
- ui
- docs
- packages/app-shell/src
- chrome
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
| 43 | + | |
| 44 | + | |
| 45 | + | |
| 46 | + | |
| 47 | + | |
0 commit comments