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

* feat(core): add stable semantic node ids to inspectScreen

* feat(core): harden semantic ID slugging with punctuation removal, empty-slug fallback, deterministic duplicates

Author: mahyarmlk

.changeset/silent-goats-dance.md

@@ -0,0 +1,5 @@
+---
+"@intent-framework/core": patch
+---
+
+Add stable semantic node IDs to `inspectScreen` output so diagnostics and graph inspection can reference deterministic semantic nodes.

docs/MVP-Checkpoint.md

@@ -34,7 +34,7 @@ It now has:
 - Resources can be runtime-scoped and reloaded.
 - Router can inject typed navigation and route context.
 - Tests can assert semantic behavior.
-- `inspectScreen()` can surface graph diagnostics.
+- `inspectScreen()` can surface graph diagnostics with deterministic semantic node IDs.
 - A small reviewer-friendly demo can be run locally.
 - CI can enforce clean-dist validation.
 

docs/Specification.md

@@ -841,6 +841,41 @@ type IntentGraph = {
 
 The graph is what enables semantic reactivity, generated runtime behavior, target-specific materialization, DevTools, testing, documentation, privacy redaction, accessibility warnings, OpenAPI generation, and AI inspection.
 
+### Graph Node Identifiers
+
+Every semantic node in `inspectScreen()` output carries a stable, deterministic `semanticId`:
+
+```ts
+type InspectedNode = {
+  id: string          // internal format: "ask_email", "act_log_in"
+  semanticId: string  // stable format: "ask:email", "action:log-in"
+  // ...
+}
+```
+
+Semantic IDs are:
+
+- deterministic for the same screen definition
+- unique within a single inspected screen
+- human-readable
+- stable across repeated `inspectScreen()` calls
+- stable even if another screen is created before this screen
+- independent of runtime instances and resource connection state
+
+Example IDs by node type:
+
+```
+screen:invite-member      → screen
+ask:email                 → ask
+ask:email-2               → duplicate ask with suffixed ID
+action:send-invite        → act
+resource:team             → resource
+surface:main              → surface
+flow:primary              → flow
+```
+
+Diagnostics reference nodes through both `nodeId` (internal format) and `semanticNodeId` (stable format). These IDs are intended for inspection, diagnostics, tests, and future DevTools. They may change when the screen structure, labels, or names change.
+
 ## Reactivity Model
 
 Intent UI should not use component rerendering as its main reactive unit.

packages/core/src/act.ts

@@ -1,5 +1,5 @@
 import { signal, createCondition, type Signal, isCondition, type Condition } from "./signal.js"
-import { registerActNode } from "./registry.js"
+import { registerActNode, getActs, nextSuffix } from "./registry.js"
 
 export type NavigationService = (name: string, params?: Record<string, string>) => void
 
@@ -154,7 +154,11 @@ export class ActBuilder<TServices extends object = DefaultScreenServices> {
   private node: ActNode<TServices>
 
   constructor(label: string) {
-    const id = `act_${label.toLowerCase().replace(/\s+/g, "_")}`
+    const baseId = `act_${label.toLowerCase().replace(/\s+/g, "_")}`
+    const existing = getActs()
+    const id = existing.has(baseId)
+      ? nextSuffix(baseId, (id) => existing.has(id))
+      : baseId
     this.node = createActNode<TServices>(id, label, [], null, undefined, false)
     registerActNode(this.node)
   }

packages/core/src/ask.ts

@@ -1,5 +1,5 @@
 import { signal, type Signal, type Condition } from "./signal.js"
-import { registerAskNode } from "./registry.js"
+import { registerAskNode, getAsks, nextSuffix } from "./registry.js"
 
 export type AskKind = "text" | "contact" | "secret" | "choice"
 
@@ -94,7 +94,11 @@ export class AskBuilder<T> {
   private node: AskNode<T>
 
   constructor(label: string, stateRef: { value: T; onChange?: (fn: (value: T) => void) => () => void }) {
-    const id = `ask_${label.toLowerCase().replace(/\s+/g, "_")}`
+    const baseId = `ask_${label.toLowerCase().replace(/\s+/g, "_")}`
+    const existing = getAsks()
+    const id = existing.has(baseId)
+      ? nextSuffix(baseId, (id) => existing.has(id))
+      : baseId
     const onChange = stateRef.onChange
     const subscribeToState = onChange
       ? (fn: () => void) => onChange((_v: T) => fn())

packages/core/src/core.test.ts

@@ -1605,6 +1605,186 @@ describe("resource invalidation", () => {
   })
 })
 
+describe("stable semantic node IDs", () => {
+  it("inspectScreen includes semanticId for all node types", () => {
+    const screenDef = screen("TestScreen", $ => {
+      const email = $.state.text("email")
+      const emailAsk = $.ask("Email", email)
+      const login = $.act("Log in")
+      $.resource("team", {
+        load: async () => "data",
+        autoLoad: false,
+      })
+      $.flow("login").startsWith(emailAsk).then(login)
+      $.surface("main").contains(emailAsk, login)
+    })
+
+    const inspected = inspectScreen(screenDef)
+    expect(inspected.semanticId).toBe("screen:test-screen")
+    expect(inspected.asks[0]?.semanticId).toBe("ask:email")
+    expect(inspected.acts[0]?.semanticId).toBe("action:log-in")
+    expect(inspected.flows[0]?.semanticId).toBe("flow:login")
+    expect(inspected.surfaces[0]?.semanticId).toBe("surface:main")
+  })
+
+  it("calling inspectScreen twice on the same screen returns the same IDs", () => {
+    const screenDef = screen("LoginScreen", $ => {
+      const email = $.state.text("email")
+      const emailAsk = $.ask("Email", email)
+      const login = $.act("Log in")
+      $.surface("main").contains(emailAsk, login)
+    })
+
+    const first = inspectScreen(screenDef)
+    const second = inspectScreen(screenDef)
+
+    expect(first.semanticId).toBe(second.semanticId)
+    expect(first.asks[0]?.semanticId).toBe(second.asks[0]?.semanticId)
+    expect(first.acts[0]?.semanticId).toBe(second.acts[0]?.semanticId)
+  })
+
+  it("creating an unrelated screen before the target screen does not change semantic IDs", () => {
+    screen("UnrelatedScreen", $ => {
+      $.ask("Name", $.state.text("name"))
+      $.act("Save")
+      $.surface("main").contains()
+    })
+
+    const screenDef = screen("LoginScreen", $ => {
+      const email = $.state.text("email")
+      const emailAsk = $.ask("Email", email)
+      const login = $.act("Log in")
+      $.surface("main").contains(emailAsk, login)
+    })
+
+    const inspected = inspectScreen(screenDef)
+    expect(inspected.semanticId).toBe("screen:login-screen")
+    expect(inspected.asks[0]?.semanticId).toBe("ask:email")
+    expect(inspected.acts[0]?.semanticId).toBe("action:log-in")
+  })
+
+  it("duplicate labels get deterministic suffixed semantic IDs", () => {
+    const screenDef = screen("Duplicates", $ => {
+      const name1 = $.state.text("name1")
+      const name2 = $.state.text("name2")
+      const ask1 = $.ask("Email", name1)
+      const ask2 = $.ask("Email", name2)
+      const act1 = $.act("Save")
+      const act2 = $.act("Save")
+      $.surface("main").contains(ask1, ask2, act1, act2)
+    })
+
+    const inspected = inspectScreen(screenDef)
+    expect(inspected.asks).toHaveLength(2)
+    expect(inspected.asks[0]?.semanticId).toBe("ask:email")
+    expect(inspected.asks[1]?.semanticId).toBe("ask:email-2")
+    expect(inspected.acts).toHaveLength(2)
+    expect(inspected.acts[0]?.semanticId).toBe("action:save")
+    expect(inspected.acts[1]?.semanticId).toBe("action:save-2")
+  })
+
+  it("diagnostics include semanticNodeId alongside nodeId", () => {
+    const screenDef = screen("DiagSemanticId", $ => {
+      const pwd = $.state.text("password")
+      const pwdAsk = $.ask("Password", pwd).asSecret()
+      $.surface("main").contains(pwdAsk)
+    })
+
+    const inspected = inspectScreen(screenDef)
+    const secretDiag = inspected.diagnostics.find(d => d.code === "secret-ask-not-private")
+    expect(secretDiag).toBeDefined()
+    expect(secretDiag?.nodeId).toBe("ask_password")
+    expect(secretDiag?.semanticNodeId).toBe("ask:password")
+  })
+
+  it("resource semanticId is stable and independent of runtime state", async () => {
+    const screenDef = screen("ResourceStable", $ => {
+      $.resource("team", {
+        load: async () => "data",
+        autoLoad: false,
+      })
+    })
+
+    const runtime = createScreenRuntime(screenDef)
+    await runtime.start()
+    const inspected = inspectScreen(screenDef, runtime.resources)
+    expect(inspected.resources[0]?.semanticId).toBe("resource:team")
+    expect(inspected.resources[0]?.id).toBe("resource_team")
+  })
+
+  it("punctuation is normalized in semantic IDs", () => {
+    const screenDef = screen("PunctuationTest", $ => {
+      const email = $.state.text("email")
+      const emailAsk = $.ask("Email!", email)
+      const login = $.act("Save!")
+      $.surface("main").contains(emailAsk, login)
+    })
+
+    const inspected = inspectScreen(screenDef)
+    expect(inspected.asks[0]?.semanticId).toBe("ask:email")
+    expect(inspected.acts[0]?.semanticId).toBe("action:save")
+  })
+
+  it("duplicate normalized labels suffix deterministically", () => {
+    const screenDef = screen("NormalizedDupes", $ => {
+      const s1 = $.state.text("s1")
+      const s2 = $.state.text("s2")
+      const ask1 = $.ask("Email", s1)
+      const ask2 = $.ask("Email!", s2)
+      const act1 = $.act("Save")
+      const act2 = $.act("Save!")
+      const act3 = $.act("Save!!")
+      $.surface("main").contains(ask1, ask2, act1, act2, act3)
+    })
+
+    const inspected = inspectScreen(screenDef)
+    expect(inspected.asks).toHaveLength(2)
+    expect(inspected.asks[0]?.semanticId).toBe("ask:email")
+    expect(inspected.asks[1]?.semanticId).toBe("ask:email-2")
+    expect(inspected.acts).toHaveLength(3)
+    expect(inspected.acts[0]?.semanticId).toBe("action:save")
+    expect(inspected.acts[1]?.semanticId).toBe("action:save-2")
+    expect(inspected.acts[2]?.semanticId).toBe("action:save-3")
+  })
+
+  it("symbol-only labels use kind-local order fallback", () => {
+    const screenDef = screen("SymbolFallback", $ => {
+      const s1 = $.state.text("s1")
+      const s2 = $.state.text("s2")
+      const act1 = $.act("!!!")
+      const act2 = $.act("???")
+      const ask1 = $.ask("***", s1)
+      const ask2 = $.ask("@@@", s2)
+      $.surface("main").contains(act1, act2, ask1, ask2)
+    })
+
+    const inspected = inspectScreen(screenDef)
+    expect(inspected.acts).toHaveLength(2)
+    expect(inspected.acts[0]?.semanticId).toBe("action:1")
+    expect(inspected.acts[1]?.semanticId).toBe("action:2")
+    expect(inspected.asks).toHaveLength(2)
+    expect(inspected.asks[0]?.semanticId).toBe("ask:1")
+    expect(inspected.asks[1]?.semanticId).toBe("ask:2")
+  })
+
+  it("diagnostics semanticNodeId uses new slugging logic", () => {
+    const screenDef = screen("DiagSlugged", $ => {
+      const pwd = $.state.text("password")
+      const pwdAsk = $.ask("Password!", pwd).asSecret()
+      const login = $.act("Log in!")
+        .primary()
+        .when(true)
+      $.surface("main").contains(pwdAsk, login)
+    })
+
+    const inspected = inspectScreen(screenDef)
+    const secretDiag = inspected.diagnostics.find(d => d.code === "secret-ask-not-private")
+    expect(secretDiag).toBeDefined()
+    expect(secretDiag?.nodeId).toBe("ask_password!")
+    expect(secretDiag?.semanticNodeId).toBe("ask:password")
+  })
+})
+
 // Type-only test helpers — these are verified during pnpm typecheck
 type _TypeTestAppServices = {
   analytics: { track(event: "login_clicked"): void }

packages/core/src/flow.ts

@@ -1,4 +1,4 @@
-import { registerFlowNode } from "./registry.js"
+import { registerFlowNode, getFlows, nextSuffix } from "./registry.js"
 import type { AnyAskNode } from "./ask.js"
 import type { ActNode } from "./act.js"
 import { AskBuilder } from "./ask.js"
@@ -16,7 +16,11 @@ export class FlowBuilder {
   private node: FlowNode
 
   constructor(name: string) {
-    const id = `flow_${name}`
+    const baseId = `flow_${name}`
+    const existing = getFlows()
+    const id = existing.has(baseId)
+      ? nextSuffix(baseId, (id) => existing.has(id))
+      : baseId
     this.node = {
       id,
       name,