Skip to content

feat(core): add stable semantic node ids to inspectScreen - #50

Merged
mahyarmlk merged 2 commits into
mainfrom
feat/inspect-screen-stable-node-ids
Jun 26, 2026
Merged

feat(core): add stable semantic node ids to inspectScreen#50
mahyarmlk merged 2 commits into
mainfrom
feat/inspect-screen-stable-node-ids

Conversation

@mahyarmlk

Copy link
Copy Markdown
Collaborator

Summary

Add deterministic, human-readable semanticId fields to inspectScreen() output for all inspected node types. Add semanticNodeId to diagnostics. Fix duplicate label/name handling to produce unique suffixed IDs.

Why

inspectScreen() output is used for diagnostics, docs, tests, future DevTools, and graph snapshots. Previously, node IDs were already deterministic but had no duplicate handling and no clean kind:slug format. This change makes IDs stable, unique, and easier to use.

Changes

  • Add semanticId: string to all inspected node types in InspectedScreen
  • Add semanticNodeId?: string to GraphDiagnostic
  • Add nextSuffix() to registry.ts for deterministic duplicate ID resolution
  • Fix AskBuilder, ActBuilder, FlowBuilder, SurfaceBuilder, and resource builder to handle duplicate labels/names
  • Add slugify() and semanticNodeId() helpers to graph.ts
  • Update docs (Specification.md, MVP-Checkpoint.md)
  • Add changeset for @intent-framework/core

ID Scheme

screen:invite-member      screen
ask:email                 ask
action:log-in             act
action:log-in-2           duplicate act with suffix
resource:team             resource
surface:main              surface
flow:login                flow

Tests

6 new tests in packages/core:

  1. inspectScreen includes semanticId for all node types
  2. calling inspectScreen twice on the same screen returns the same IDs
  3. creating an unrelated screen before the target screen does not change semantic IDs
  4. duplicate labels get deterministic suffixed semantic IDs
  5. diagnostics include semanticNodeId alongside nodeId
  6. resource semanticId is stable and independent of runtime state

Validation

  • pnpm test: 316 tests pass (133 core, 86 dom, 72 router, 21 testing, 4 server)
  • pnpm typecheck: passes
  • pnpm build: passes
  • pnpm lint: passes
  • pnpm pack:check: passes
  • pnpm changeset status: shows @intent-framework/core patch bump

Known limitations

None.

Follow-up

None.

@mahyarmlk
mahyarmlk force-pushed the feat/inspect-screen-stable-node-ids branch from 9492a41 to 2a4fe65 Compare June 26, 2026 07:39
@mahyarmlk
mahyarmlk merged commit 73ab269 into main Jun 26, 2026
1 check passed
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.

1 participant