Merge pull request #57 from intent-framework/docs/resource-semantics-guide

mahyarmlk · web-flow · commit 37a3cad88423 · 2026-06-26T12:34:55.000+03:30
docs: add resource semantics guide
diff --git a/README.md b/README.md
@@ -244,6 +244,8 @@ The demo shows a small team invite flow:
 
 For a guided walkthrough, see [Demo Guide](docs/Demo.md).
 
+For a deep dive into resource semantics — load, reload, invalidation, staleness, and runtime scoping — see the [Resources Guide](docs/Resources.md).
+
 ## What the demo demonstrates
 
 The demo is intentionally small. It is a dagger, not a cathedral.
diff --git a/docs/Inspect-Screen.md b/docs/Inspect-Screen.md
@@ -48,6 +48,8 @@ Each action includes: `id`, `semanticId`, `label`, `primary`, `enabled`, `blocke
 
 Each resource includes: `id`, `semanticId`, `name`, `status`, `hasValue`, `stale`, `error`.
 
+For a detailed explanation of resource lifecycle, runtime scoping, and invalidation, see the [Resources Guide](Resources.md).
+
 Resources require passing runtime resource nodes:
 
 ```ts
diff --git a/docs/MVP-Checkpoint.md b/docs/MVP-Checkpoint.md
@@ -142,9 +142,10 @@ Do not jump into these without a very specific narrow PR:
 ## Documented
 
 - ✅ `inspectScreen()` diagnostic guide (`docs/Inspect-Screen.md`) — covers graph contents, all five current diagnostics, semantic ID behavior, development workflow, and current boundaries.
+- ✅ Resource semantics guide (`docs/Resources.md`) — covers resource lifecycle, runtime scoping, ResourceRef vs ResourceNode, invalidation, loader context, and current boundaries.
 
 ## Recommended next moves
 
 1. ~~Add a tiny diagnostics/dev-inspection page or command that prints `inspectScreen()` output for demo screens without `MutationObserver`.~~ (Covered by the diagnostic guide documenting the `demo-panels.ts` pattern.)
-2. Improve resource semantics documentation: runtime-scoped resources, reload, stale, invalidation, context.
+2. ~~Improve resource semantics documentation: runtime-scoped resources, reload, stale, invalidation, context.~~ (Covered by docs/Resources.md.)
 3. Add one or two graph diagnostics that catch real authoring mistakes before adding any new package.
diff --git a/docs/Quickstart.md b/docs/Quickstart.md
@@ -225,6 +225,7 @@ Intent does not replace components for everything. It replaces components as the
    pnpm dev:canonical
    ```
 2. See the [web demo](../examples/web-basic) for a full team invite flow with routing, resources, and diagnostics.
-3. Read the [Specification](Specification.md) for the architecture.
-4. Read the [Inspect Screen and Diagnostics Guide](Inspect-Screen.md) for a detailed walkthrough of `inspectScreen()`, diagnostics, and semantic IDs.
-5. Check the [MVP Checkpoint](MVP-Checkpoint.md) for current boundaries.
+3. Read the [Resources Guide](Resources.md) for resource semantics — load, reload, invalidation, runtime scoping.
+4. Read the [Specification](Specification.md) for the architecture.
+5. Read the [Inspect Screen and Diagnostics Guide](Inspect-Screen.md) for a detailed walkthrough of `inspectScreen()`, diagnostics, and semantic IDs.
+6. Check the [MVP Checkpoint](MVP-Checkpoint.md) for current boundaries.
diff --git a/docs/Resources.md b/docs/Resources.md
@@ -0,0 +1,264 @@
+# Resource Semantics Guide
+
+## What a resource is
+
+A resource is semantic async state owned by a screen runtime.
+
+It represents data a screen needs — a team roster, a user profile, a document. It is not a global cache or a data-fetching library. Resources are part of the product graph, like asks and actions.
+
+The current API:
+
+```ts
+const team = $.resource("team", {
+  load: async ({ route }) => {
+    return loadTeam(route.params.teamId)
+  },
+})
+```
+
+`$.resource(name, config)` returns a `ResourceRef<T, TServices>` — a definition-time handle. The loader is an async function that returns the resource value. `autoLoad` defaults to `true`.
+
+## Minimal example
+
+```ts
+import { screen } from "@intent-framework/core"
+
+type AppServices = {
+  navigate?: (name: string) => void
+}
+
+const loadProfile = async (id: string): Promise<{ name: string; email: string }> => {
+  const res = await fetch(`/api/profiles/${id}`)
+  return res.json()
+}
+
+export const ProfileScreen = screen<AppServices>("Profile", $ => {
+  const profile = $.resource("profile", {
+    load: async () => loadProfile("user_1"),
+  })
+
+  const refresh = $.act("Refresh")
+    .does(async () => {
+      await profile.reload()
+    })
+
+  $.surface("main").contains(refresh)
+})
+```
+
+The resource loads when the runtime starts (autoload). The action calls `profile.reload()` to re-fetch. The loader receives runtime services as context.
+
+## Runtime-scoped resources
+
+Resource definitions live on the screen definition. Resource instances live inside a `ScreenRuntime`.
+
+When you call `createScreenRuntime()` or `testScreen()`, the runtime creates fresh `ResourceNode` instances:
+
+```ts
+const runtime1 = createScreenRuntime(ProfileScreen)
+await runtime1.start()
+// runtime1 has its own ResourceNode for "profile"
+
+const runtime2 = createScreenRuntime(ProfileScreen)
+await runtime2.start()
+// runtime2 has a separate ResourceNode, independent of runtime1
+
+runtime1.dispose()
+// runtime1's resource nodes disconnect; runtime2's nodes are unaffected
+```
+
+**Key behaviors:**
+
+- Starting a runtime creates new resource nodes from the screen's configs.
+- Disposing the runtime disconnects `ResourceRef` proxies from their nodes.
+- Two runtimes do not share live resource state. Loading a resource in one runtime does not affect another.
+
+**Current limitation:** A `ResourceRef` proxies one connected runtime at a time. The last runtime to `start()` owns the ref. Full concurrent multi-mount semantics for the same ref across multiple active runtimes are future work.
+
+## ResourceRef vs ResourceNode
+
+| Concept | Role |
+|---------|------|
+| `ResourceRef` | Definition-time handle returned by `$.resource()`. Proxies status, value, conditions, and methods to whichever `ResourceNode` it is currently connected to. |
+| `ResourceNode` | Runtime-owned instance holding current status, value, error, stale state, and conditions. Created by `ScreenRuntime.start()`. |
+
+Users hold `ResourceRef` handles (e.g. `const team = $.resource("team", ...)`). The ref connects to a runtime node automatically on `start()` and disconnects on `dispose()`.
+
+## Loading lifecycle
+
+### Statuses
+
+A resource transitions through these statuses:
+
+| Status | Meaning |
+|--------|---------|
+| `"idle"` | Not yet loaded. Initial state before any `load()` call. |
+| `"pending"` | Loader is running. |
+| `"ready"` | Loader completed successfully. `value` is set. |
+| `"failed"` | Loader threw an error. `error` is set. |
+
+### Conditions
+
+Each status has a corresponding `Condition`:
+
+| Condition | True when |
+|-----------|-----------|
+| `resource.ready` | `status === "ready"` |
+| `resource.pending` | `status === "pending"` |
+| `resource.failed` | `status === "failed"` |
+| `resource.stale` | Resource was invalidated and has not been reloaded successfully since. |
+
+Conditions are cached: `resource.ready === resource.ready`.
+
+### Lifecycle steps
+
+1. **Definition** — `$.resource("name", { load, autoLoad })` creates a `ResourceRef`. No loading happens yet.
+2. **Runtime start** — `ScreenRuntime.start()` creates `ResourceNode` instances, connects refs, and calls `load()` for resources with `autoLoad: true` (the default).
+3. **Manual load** — `resource.load(context?)` runs the loader, sets status to `"pending"`, then `"ready"` or `"failed"`.
+4. **Reload** — `resource.reload(context?)` works identically to `load()`. If no context is given, it reuses the last context from the previous load.
+5. **Invalidation** — `resource.invalidate()` sets `stale` to `true`. It does not trigger a reload.
+6. **Successful load clears stale** — After `load()` or `reload()` succeeds, `stale` returns to `false` and `status` becomes `"ready"` again.
+7. **Failed load** — If the loader throws, `status` becomes `"failed"`, `error` is set, and `stale` is cleared (the resource is failed, not stale).
+
+### autoLoad behavior
+
+By default `autoLoad: true`. Set `autoLoad: false` to defer loading:
+
+```ts
+const team = $.resource("team", {
+  load: async () => loadTeam("team_1"),
+  autoLoad: false,
+})
+
+// Later, manually:
+await team.reload()
+```
+
+## Action invalidation
+
+Actions can mark resources as stale after successful execution:
+
+```ts
+const save = $.act("Save")
+  .does(async () => { /* mutate data */ })
+  .invalidates(team, members)
+```
+
+Rules:
+
+- **Success invalidates.** After the action handler completes without throwing, each listed resource is invalidated (marked stale).
+- **Blocked actions do nothing.** If the action is blocked by a condition, `executeAct()` returns early and resources are not invalidated.
+- **Failed actions do nothing.** If the handler throws, invalidation is skipped.
+- **Invalidation marks stale only.** It does not reload. The resource stays `ready` (value is still available) but `stale` becomes `true`. Reload manually if needed.
+
+## Loader context
+
+Resource loaders receive runtime services as context:
+
+```ts
+type AppServices = {
+  route: RouteContext<AppRoutes>
+}
+
+const team = $.resource("team", {
+  load: async ({ route }) => {
+    return loadTeam(route.params.teamId)
+  },
+})
+```
+
+The context is the same `ActionExecutionContext<TServices>` that actions receive:
+
+- Autoload passes the runtime's services to the loader.
+- `resource.load(context)` passes the given context.
+- `resource.reload()` without arguments reuses the last context from the prior load.
+- `resource.reload(context)` passes the given context explicitly.
+
+A loader that takes no context argument is also supported:
+
+```ts
+$.resource("team", {
+  load: async () => loadTeam("team_1"),
+})
+```
+
+## Using resources in tests
+
+The `@intent-framework/testing` package exposes resources through the `ScreenHandle`:
+
+```ts
+import { test, expect } from "vitest"
+import { testScreen } from "@intent-framework/testing"
+import { ProfileScreen } from "./ProfileScreen.js"
+
+test("resource loads and can be reloaded", async () => {
+  await testScreen(ProfileScreen, async app => {
+    const team = app.resource("team")
+    expect(team.status()).toBe("ready")
+    expect(team.stale()).toBe(false)
+
+    team.invalidate()
+    expect(team.stale()).toBe(true)
+
+    await team.reload()
+    expect(team.stale()).toBe(false)
+    expect(team.status()).toBe("ready")
+  })
+})
+```
+
+The harness creates a runtime, autoloads resources, and provides methods to check status, load, reload, invalidate, and check staleness.
+
+Resources with `autoLoad: false` stay idle until manually loaded:
+
+```ts
+test("autoLoad: false resource stays idle", async () => {
+  await testScreen(ProfileScreen, async app => {
+    const profile = app.resource("profile")
+    expect(profile.status()).toBe("idle")
+    await profile.load()
+    expect(profile.status()).toBe("ready")
+  })
+})
+```
+
+## inspectScreen and resources
+
+Resources appear in `inspectScreen()` output when you pass runtime resource nodes:
+
+```ts
+const runtime = createScreenRuntime(MyScreen)
+await runtime.start()
+const graph = inspectScreen(MyScreen, runtime.resources)
+console.log(graph.resources)
+```
+
+Each inspected resource includes:
+
+```json
+{
+  "id": "resource_team",
+  "semanticId": "resource:team",
+  "name": "team",
+  "status": "ready",
+  "hasValue": true,
+  "stale": false,
+  "error": undefined
+}
+```
+
+On failure, `error` contains the error message and `status` is `"failed"`.
+
+See the [Inspect Screen and Diagnostics Guide](Inspect-Screen.md) for more detail.
+
+## Current boundaries
+
+Resources are intentionally limited:
+
+- **No global cache.** Each runtime owns its resource nodes. There is no shared cache between runtimes.
+- **No cache keys.** Resource identity is by name within a screen. There is no key-based deduplication or caching.
+- **No staleTime.** Invalidation is manual or action-driven. There is no TTL-based staleness.
+- **No automatic background refetching.** Stale resources stay stale until explicitly reloaded.
+- **No Suspense integration.** Resources do not integrate with React Suspense or any other framework's loading boundaries.
+- **No server framework integration yet.** Resources live on screen definitions and runtimes. Server-side resource hydration is not implemented.
+- **No full concurrent multi-mount resource ref semantics.** A `ResourceRef` connects to one runtime at a time. The last runtime to start owns the ref.
