Skip to content

docs(runner): README §Features 的 Hot Reload 按两个 loader 分路限定 (#3620) - #3634

Merged
yinlianghui merged 1 commit into
mainfrom
claude/issue-3620-readme-hotreload-claim
Aug 7, 2026
Merged

docs(runner): README §Features 的 Hot Reload 按两个 loader 分路限定 (#3620)#3634
yinlianghui merged 1 commit into
mainfrom
claude/issue-3620-readme-hotreload-claim

Conversation

@yinlianghui

@yinlianghui yinlianghui commented Aug 7, 2026

Copy link
Copy Markdown
Collaborator

Fixes #3620

前提复核(对 origin/main,切点 0e4ea07b2)

分诊已核过一轮,这里独立复核一遍,三条全部成立、行号未漂:

?api= 不是边角情况:本文件 §Metadata Loading(#3537 / PR #3581 补)把它作为与本地路并列的加载方式正式记录,还带一张 loader 对照表。而 §Features 站在全文最前面,读者先读到它。

改写前后对照

改前

- **Hot Reload** - Automatic reload on schema changes

改后

- **No-Restart Edits** - Under `src/app-data/` the dev server picks metadata changes up
  without a restart, because that JSON is part of Vite's module graph; behind `?api=` it
  cannot, because Vite never sees your backend ([Metadata Loading](#metadata-loading))

措辞与 PR #3621(#3604)刚落地的 §Development Workflow 第 3 步逐字对齐,同一从句原样复用 —— 这条单子要的就是「同页一个声音」:

3. Edit the metadata. Under `src/app-data/` the dev server picks the change up without a
   restart, because that JSON is part of Vite's module graph; behind `?api=` it cannot,
   because Vite never sees your backend. Reload the page if the view still shows the
   previous document.

改后 grep -n "Vite's module graph" 命中 :9(§Features)与 :114(§Development Workflow)两行,同一句话。第 3 步末尾那句「视图仍是旧文档就刷新页面」是操作建议,留在 workflow 一节不重复进 Features;Features 这条改为指向 §Metadata Loading,由那一节把两条路的差别和 src/app-data/ git-ignored 的坑讲清楚(:75-78),正是 #3620 正文给的两个建议之一。

列表顺序与其余四条 bullet 未动,改动严格限于这一个 bullet(diff:1 file changed, 3 insertions, 1 deletion)。

为什么标题也从 "Hot Reload" 改掉

派发只点名了正文那句无条件宣称,但加粗标题必须一起动,否则改不干净 —— 「Hot Reload」这个词本身就是断言「更新会自己出现在屏幕上」,而这正是 PR #3621 明确拒绝写下的那一条。#3621 的理由在本次复核里仍然成立,原样确认:

  • src/App.tsx 导出组件(RunnerApp)加一个空 export {}(:10),是 react-refresh 的边界;JSON 变更冒泡到这个边界后,可能是整页 reload,也可能被一次保状态的重渲染吸收。
  • 后者下 pageSchema 这个 useState 不变、读取它的 useEffect 依赖 [currentPath, loader] 也不变(loader 是 useMemo(…, []),:88-101),重新读取不会发生,读者看到的仍是旧文档。

判定这一点需要真起 dev server 在浏览器里看,本任务范围内不含实跑。所以正文只落在能从代码确认的那半 ——「dev server 无需重启就能读到改动」是服务端事实,不承诺屏幕行为;标题也换成同量级的 "No-Restart Edits"。留着 "Hot Reload" 而正文写限定,等于把 #3620 要消除的那个矛盾从「跨节」搬成「同一条 bullet 内部」。

维护者若希望把这里强化成明确的「自动刷新」,前置是先起一次 dev server 实测,可另开一趟做 —— 与 #3621 留的口子一致。

验证

改动是单文件 markdown,如实写明每条证据的覆盖面,不拿不覆盖本文件的绿灯充当背书:

命令 结果 覆盖面
node scripts/check-control-bytes.mjs ✅ OK (scanned 3654 tracked text file(s); skipped 85 binary) 覆盖本文件 —— 该脚本以 git ls-files -z 为扫描面
node scripts/check-doc-links.mjs Links are valid across 6 scan roots. 不覆盖本文件 —— SCAN_ROOTS(scripts/check-doc-links.mjs:355-362)是 content/docs、examples、README.md、CONTRIBUTING.md、ROADMAP.md、docs。已对本次基线重新确认:PR #3629 让门禁认站内绝对 URL,但并未把 packages/** 加进扫描面。改前改后都绿,不构成对本改动的背书
grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f]' packages/runner/README.md 无输出(rc=1),改前的 blob 同样干净 门禁盲区自扫
grep -c $'’' packages/runner/README.md 0 新增的 Vite's 用 ASCII 直角撇号,与文件既有的 :76 / :114 一致,未混入弯引号

新增的 [Metadata Loading](#metadata-loading) 锚点:目标是本文件 ## Metadata Loading,且同文件 :96 / :102 已经在用同一个锚点,不是新拼法。

未跑 pnpm test / pnpm type-check,这是判断不是遗漏,与 #3621 同:改动是 markdown,不被任何代码路径导入,packages/runner 的测试也不读 README;仓库的 ci.yml 与 lint.yml 对 **/*.md 走 paths-ignore,本 PR 在 CI 上只会触发 control-bytes.yml(无 path 过滤)。为一个必然无关的结果去装一整棵 node_modules 并构建依赖,不符合共享容器的资源纪律 —— 本 worktree 因此也未 pnpm install,上面两个门禁脚本都是零依赖的 node 脚本。

无 changeset

与 #3602、#3621(同一文件、同样只改 README)两次先例一致:包 README 的文档修正不进 changeset。changeset-guard.yml 的触发条件是 paths: .changeset/**,不会因为缺 changeset 而红。

越界发现(未在本 PR 修改)

按派发要求通读了 §Features 全列表,一条新发现,已单独立单:

§Features 其余三条一并核过,无同类无条件宣称,故未动:Development Ready(package.json 的 dev: vite,vite 在 devDependencies 里,属实)、Production Build(build: vite build,属实)、Schema Development(通用表述,不含可证伪的机制断言)。

🤖 Generated with Claude Code

https://claude.ai/code/session_01GTRjn8xBqp75dk7kFupVRt

Generated by Claude Code

@claude
docs(runner): README §Features 的 Hot Reload 按两个 loader 分路限定 (#3620)
5a52568 
§Features 第 8 行的 `- **Hot Reload** - Automatic reload on schema changes` 是一句
无条件宣称,与 PR #3621(#3604)刚在同文件 §Development Workflow 第 3 步落地的分路
限定相矛盾 —— 同一页两个声音。

按第 3 步的口径改写这一个 bullet,措辞与之逐字对齐:
- `src/app-data/` 一侧只写代码可证的部分 —— JSON 经 `import.meta.glob`
  (`src/lib/MetadataLoader.ts:26-28`)进入 Vite 的 module graph,dev server 无需
  重启即可读到改动;
- `?api=` 一侧的否定无条件成立 —— `NetworkLoader` 在运行时 `fetch`(同文件
  :89/:101),后端完全在 Vite 视野之外,不存在任何 watch/reload 机制。

标题也从 "Hot Reload" 改掉:该词本身就是「更新会自己出现在屏幕上」这个断言,
而这正是 PR #3621 因无法脱离实跑从代码确认而明确拒绝写下的那一条。留着它,正文
的限定与加粗标题仍然打架。

列表顺序与其余四条 bullet 未动。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GTRjn8xBqp75dk7kFupVRt
@vercel

vercel Bot commented Aug 7, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment
Project Deployment Actions Updated (UTC)
objectui Ignored Ignored Aug 7, 2026 4:35pm

Request Review

@github-actions github-actions Bot added the documentation Improvements or additions to documentation label Aug 7, 2026
@yinlianghui yinlianghui mentioned this pull request Aug 7, 2026
Closed
@yinlianghui
yinlianghui marked this pull request as ready for review August 7, 2026 16:37
@yinlianghui
yinlianghui added this pull request to the merge queue Aug 7, 2026
@github-actions

github-actions Bot commented Aug 7, 2026

Copy link
Copy Markdown
Contributor

✅ Console Performance Budget

Metric Value Budget
Main entry (gzip) 28.1 KB 350 KB
Entry file index-BMmpqD1l.js —
Status PASS —

📦 Bundle Size Report

Package Size Gzipped
app-shell (index.js) 8.66KB 3.13KB
app-shell (runtime-config.js) 7.42KB 2.32KB
app-shell (types.js) 0.01KB 0.04KB
app-shell (urlParams.js) 7.57KB 2.97KB
auth (AuthContext.js) 0.31KB 0.24KB
auth (AuthGuard.js) 1.17KB 0.53KB
auth (AuthProvider.js) 22.10KB 4.37KB
auth (AuthShell.js) 3.49KB 1.40KB
auth (ForgotPasswordForm.js) 12.21KB 3.45KB
auth (LoginForm.js) 18.13KB 5.39KB
auth (PreviewBanner.js) 0.90KB 0.50KB
auth (RegisterForm.js) 6.64KB 2.21KB
auth (SocialSignInButtons.js) 9.60KB 3.89KB
auth (UserMenu.js) 3.40KB 1.22KB
auth (auth-gate-events.js) 1.29KB 0.66KB
auth (authStyles.js) 5.04KB 1.72KB
auth (createAuthClient.js) 35.76KB 9.11KB
auth (createAuthenticatedFetch.js) 4.37KB 1.69KB
auth (index.js) 2.35KB 1.07KB
auth (org-roles.js) 6.66KB 2.78KB
auth (phone-identifier.js) 1.11KB 0.66KB
auth (types.js) 0.59KB 0.35KB
auth (useAuth.js) 4.91KB 0.87KB
auth (useIsWorkspaceAdmin.js) 1.61KB 0.85KB
collaboration (CommentThread.js) 26.07KB 7.56KB
collaboration (LiveCursors.js) 3.17KB 1.27KB
collaboration (PresenceAvatars.js) 6.49KB 2.64KB
collaboration (PresenceProvider.js) 2.79KB 1.13KB
collaboration (index.js) 1.65KB 0.73KB
collaboration (useCollaborationTranslation.js) 6.05KB 2.52KB
collaboration (useCommentSearch.js) 1.98KB 0.88KB
collaboration (useConflictResolution.js) 7.75KB 1.86KB
collaboration (useMentionNotifications.js) 1.81KB 0.68KB
collaboration (usePresence.js) 6.33KB 1.84KB
collaboration (useRealtimeSubscription.js) 7.91KB 2.01KB
components (index.js) 480.72KB 105.64KB
core (index.js) 2.96KB 1.13KB
create-plugin (index.js) 9.28KB 2.98KB
data-objectstack (index.js) 137.51KB 35.11KB
fields (index.js) 230.87KB 56.83KB
i18n (LocalizationContext.js) 1.76KB 0.96KB
i18n (currency.js) 1.22KB 0.64KB
i18n (i18n.js) 4.32KB 1.77KB
i18n (index.js) 2.65KB 1.06KB
i18n (pickLocalized.js) 1.70KB 0.83KB
i18n (provider.js) 9.48KB 3.27KB
i18n (useObjectLabel.js) 26.14KB 6.07KB
i18n (useSafeTranslation.js) 4.52KB 1.96KB
layout (index.js) 38.53KB 10.71KB
mobile (MobileProvider.js) 0.92KB 0.49KB
mobile (ResponsiveContainer.js) 0.94KB 0.38KB
mobile (breakpoints.js) 1.51KB 0.70KB
mobile (createOfflineDataSource.js) 5.61KB 1.74KB
mobile (index.js) 1.50KB 0.62KB
mobile (offlineQueue.js) 3.91KB 1.35KB
mobile (pwa.js) 0.97KB 0.49KB
mobile (serviceWorker.js) 1.48KB 0.62KB
mobile (serviceWorkerSource.js) 3.41KB 1.48KB
mobile (useBreakpoint.js) 1.54KB 0.65KB
mobile (useGesture.js) 6.96KB 1.98KB
mobile (useOfflineSync.js) 1.99KB 0.72KB
mobile (usePullToRefresh.js) 2.53KB 0.85KB
mobile (useResponsive.js) 0.71KB 0.42KB
mobile (useResponsiveConfig.js) 1.36KB 0.63KB
mobile (useSpecGesture.js) 4.32KB 1.64KB
mobile (useTouchTarget.js) 1.01KB 0.54KB
permissions (MePermissionsProvider.js) 8.75KB 3.06KB
permissions (PermissionContext.js) 0.31KB 0.25KB
permissions (PermissionGuard.js) 0.89KB 0.45KB
permissions (PermissionProvider.js) 3.67KB 1.12KB
permissions (evaluator.js) 4.41KB 1.44KB
permissions (index.js) 0.91KB 0.41KB
permissions (store.js) 0.91KB 0.42KB
permissions (useFieldPermissions.js) 1.28KB 0.52KB
permissions (usePermissions.js) 1.55KB 0.71KB
plugin-ai (index.js) 15.71KB 3.79KB
plugin-calendar (index.js) 44.98KB 12.37KB
plugin-charts (index.js) 61.04KB 17.31KB
plugin-chatbot (index.js) 180.09KB 42.72KB
plugin-dashboard (index.js) 115.50KB 29.96KB
plugin-designer (index.js) 210.51KB 42.51KB
plugin-detail (index.js) 232.79KB 57.42KB
plugin-editor (index.js) 2.46KB 1.10KB
plugin-form (index.js) 112.10KB 27.10KB
plugin-gantt (index.js) 162.55KB 39.57KB
plugin-grid (index.js) 186.61KB 49.34KB
plugin-kanban (index.js) 48.30KB 13.28KB
plugin-list (index.js) 105.12KB 25.48KB
plugin-map (index.js) 16.81KB 5.24KB
plugin-markdown (index.js) 13.72KB 4.69KB
plugin-report (index.js) 40.58KB 10.58KB
plugin-timeline (index.js) 25.76KB 7.33KB
plugin-tree (index.js) 8.50KB 2.88KB
plugin-view (index.js) 84.03KB 20.55KB
providers (DataSourceProvider.js) 0.75KB 0.39KB
providers (MetadataProvider.js) 1.37KB 0.59KB
providers (ThemeProvider.js) 1.90KB 0.85KB
providers (UploadProvider.js) 11.71KB 3.53KB
providers (index.js) 0.44KB 0.22KB
providers (types.js) 0.01KB 0.04KB
react-runtime (index.js) 5.67KB 2.37KB
react (LazyPluginLoader.js) 3.77KB 1.33KB
react (SchemaRenderer.js) 19.28KB 6.38KB
react (data-invalidation.js) 5.05KB 2.08KB
react (index.js) 1.02KB 0.55KB
react (spec-input.js) 0.20KB 0.18KB
sdui-parser (codegen.js) 4.09KB 1.74KB
sdui-parser (index.js) 4.47KB 2.03KB
sdui-parser (parse.js) 10.04KB 2.82KB
sdui-parser (types.js) 0.29KB 0.24KB
sdui-parser (validate.js) 4.69KB 1.48KB
types (ai.js) 0.20KB 0.17KB
types (api-types.js) 0.20KB 0.18KB
types (app.js) 2.87KB 0.99KB
types (base.js) 0.20KB 0.18KB
types (blocks.js) 0.20KB 0.18KB
types (complex.js) 0.20KB 0.18KB
types (crud.js) 0.20KB 0.18KB
types (data-display.js) 0.20KB 0.18KB
types (data-protocol.js) 0.20KB 0.19KB
types (data.js) 0.20KB 0.18KB
types (designer.js) 1.87KB 0.85KB
types (disclosure.js) 0.20KB 0.18KB
types (error-code.js) 1.54KB 0.88KB
types (feedback.js) 0.20KB 0.18KB
types (field-types.js) 0.20KB 0.18KB
types (form.js) 0.20KB 0.18KB
types (http-retry.js) 4.32KB 2.02KB
types (index.js) 2.71KB 1.34KB
types (layout.js) 0.20KB 0.18KB
types (managed-by.js) 0.19KB 0.18KB
types (mobile.js) 2.59KB 1.31KB
types (navigation.js) 0.20KB 0.18KB
types (objectql.js) 0.20KB 0.18KB
types (overlay.js) 0.20KB 0.18KB
types (permissions.js) 0.20KB 0.18KB
types (plugin-scope.js) 0.20KB 0.18KB
types (record-components.js) 0.20KB 0.19KB
types (record-semantics.js) 1.28KB 0.67KB
types (registry.js) 0.20KB 0.18KB
types (reports.js) 0.20KB 0.18KB
types (spec-report.js) 5.05KB 1.93KB
types (system-fields.js) 3.33KB 1.54KB
types (theme.js) 0.20KB 0.18KB
types (ui-action.js) 3.40KB 1.71KB
types (views.js) 0.20KB 0.18KB
types (widget.js) 0.20KB 0.18KB

Size Limits

  • ✅ Core packages should be < 50KB gzipped
  • ✅ Component packages should be < 100KB gzipped
  • ⚠️ Plugin packages should be < 150KB gzipped

Merged via the queue into main with commit 8098c85 Aug 7, 2026
7 checks passed
@yinlianghui
yinlianghui deleted the claude/issue-3620-readme-hotreload-claim branch August 7, 2026 16:37
This was referenced Aug 7, 2026
Closed
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

documentation Improvements or additions to documentation

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

packages/runner/README.md §Features 的「Hot Reload - Automatic reload on schema changes」未按 loader 分路,?api= 那条不成立

2 participants

@yinlianghui @claude