@bluelibs/runner-dev 6.2.0 → 6.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bluelibs/runner-dev",
-  "version": "6.2.0",
+  "version": "6.4.0",
   "description": "BlueLibs Runner DevTools",
   "main": "dist/index.js",
   "repository": {
@@ -11,6 +11,8 @@
     "build": "tsc -p config/ts/tsconfig.json && npm run build:ui",
     "watch": "tsc -p config/ts/tsconfig.json -w",
     "clean": "rm -rf dist",
+    "skills:pack:materialize": "node ./scripts/pack-npm-skills.mjs materialize",
+    "skills:pack:restore": "node ./scripts/pack-npm-skills.mjs restore",
     "cli": "ts-node --project config/ts/tsconfig.json src/cli.ts",
     "cli:local": "ts-node --project config/ts/tsconfig.json src/cli.ts",
     "start": "node dist/main.js",
@@ -21,6 +23,7 @@
     "build:ui:watch": "cd src/ui && vite build --watch --clearScreen=false",
     "play:server": "tsx watch --tsconfig config/ts/tsconfig.json src/__tests__/dummy/dummyServer.ts",
     "test": "jest --config config/jest/jest.config.js --verbose --runInBand",
+    "test:qa": "node ./scripts/run-jest-summary.mjs",
     "test:dev": "jest --config config/jest/jest.config.js --verbose --watch",
     "coverage": "jest --config config/jest/jest.config.js --verbose --coverage",
     "test:clean": "jest --config config/jest/jest.config.js --clearCache",
@@ -31,16 +34,19 @@
     "typedoc": "typedoc --options config/typedoc/typedoc.json",
     "lint": "eslint src --config config/eslint/eslint.config.mjs",
     "lint:fix": "eslint src --config config/eslint/eslint.config.mjs --fix",
-    "qa": "npm run lint:fix && npm run typecheck && npm run build && npm run test && npm run typedoc",
+    "qa": "npm run lint:fix && npm run typecheck && npm run build && npm run test:qa && npm run typedoc",
     "coverage:ai": "jest --config config/jest/jest.config.js --coverage --coverageReporters=text-summary",
     "codegen": "graphql-codegen --config config/codegen.ts",
     "prebuild": "ts-node --project config/ts/tsconfig.json scripts/sync-version.ts && npm run codegen",
     "play": "concurrently -k -n UI,SRV -c blue,green \"npm:build:ui:watch\" \"npm:play:server\"",
     "play:cli": "npm run play:server",
+    "play:export": "ts-node --project config/ts/tsconfig.json src/__tests__/dummy/exportPlayCatalog.ts",
     "demo:ping": "ENDPOINT=http://localhost:31337/graphql node dist/cli.js ping",
     "demo:query": "ENDPOINT=http://localhost:31337/graphql node dist/cli.js query 'query { tasks { id } }' --format pretty",
     "demo:overview": "ENDPOINT=http://localhost:31337/graphql node dist/cli.js overview --details 5",
-    "sync:docs": "ts-node --project config/ts/tsconfig.json scripts/sync-docs.ts"
+    "postinstall": "npm-skills extract --skip-production --override",
+    "prepack": "npm run build && npm run skills:pack:materialize",
+    "postpack": "npm run skills:pack:restore"
   },
   "bin": {
     "runner-dev": "dist/cli.js"
@@ -106,7 +112,6 @@
     "@adobe/jsonschema2md": "^8.0.5",
     "@apollo/server": "^5.0.0",
     "@as-integrations/express5": "^1.1.2",
-    "@bluelibs/runner": "^6.2.0",
     "@bluelibs/smart": "^2.2.1",
     "@modelcontextprotocol/sdk": "^1.17.2",
     "@types/prismjs": "^1.26.5",
@@ -114,6 +119,7 @@
     "express": "^5.0.0",
     "graphql": "^16.11.0",
     "lru-cache": "^11.1.0",
+    "npm-skills": "^0.4.0",
     "prismjs": "^1.30.0",
     "react": "18.3.1",
     "react-dom": "18.3.1",
@@ -128,6 +134,13 @@
       "react-dom": "18.3.1"
     }
   },
+  "npmSkills": {
+    "consume": {
+      "only": [
+        "@bluelibs/runner"
+      ]
+    }
+  },
   "prettier": {
     "trailingComma": "es5",
     "tabWidth": 2,
@@ -143,5 +156,8 @@
         }
       }
     ]
+  },
+  "peerDependencies": {
+    "@bluelibs/runner": "^6.4.0"
   }
 }

package/readmes/API_REFERENCE.md

@@ -0,0 +1,352 @@
+# GraphQL API Reference
+
+This document tracks the current `@bluelibs/runner-dev` GraphQL surface.
+It has been refreshed for the current SDL and focuses on the entry points people actually reach for first: root queries, mutations, live telemetry, and the higher-signal topology types.
+
+If you need the complete schema SDL instead of the guided summary below, print it directly from the current build:
+
+```bash
+# Against a running app
+runner-dev schema sdl --endpoint http://localhost:1337/graphql
+
+# Or in dry-run mode from a local entry file
+runner-dev schema sdl --entry-file src/main.ts
+```
+
+## Highlights
+
+- Introspection spans tasks, hooks, resources, events, tags, errors, async contexts, middleware, run options, and interceptor ownership.
+- Resource docs now include `isolation`, `subtree`, cooldown/ready/health flags, and resolved registrations.
+- Task docs include durable workflow metadata, RPC lane summary, and runtime interceptor ownership.
+- Live telemetry includes logs, event emissions, errors, runs, process stats, and per-resource health reports.
+- Mutations cover task swapping, unswapping, task/event invocation, file editing, and guarded eval.
+
+## Query Root
+
+The current `Query` type exposes:
+
+- `root: Resource`
+- `runOptions: RunOptions!`
+- `interceptorOwners: InterceptorOwnersSnapshot!`
+- `all(idIncludes: ID): [BaseElement!]!`
+- `tags: [Tag!]!`
+- `tag(id: ID!): Tag`
+- `task(id: ID!): Task`
+- `tasks(idIncludes: ID): [Task!]!`
+- `hook(id: ID!): Hook`
+- `hooks(idIncludes: ID): [Hook!]!`
+- `resource(id: ID!): Resource`
+- `resources(idIncludes: ID): [Resource!]!`
+- `event(id: ID!): Event`
+- `events(filter: EventFilterInput): [Event!]!`
+- `middleware(id: ID!): Middleware`
+- `middlewares(idIncludes: ID): [Middleware!]!`
+- `taskMiddlewares(idIncludes: ID): [TaskMiddleware!]!`
+- `resourceMiddlewares(idIncludes: ID): [ResourceMiddleware!]!`
+- `error(id: ID!): Error`
+- `errors(idIncludes: ID): [Error!]!`
+- `asyncContext(id: ID!): AsyncContext`
+- `asyncContexts(idIncludes: ID): [AsyncContext!]!`
+- `live: Live!`
+- `diagnostics: [Diagnostic!]!`
+- `swappedTasks: [SwappedTask!]!`
+
+### Common Query Filters
+
+- `EventFilterInput`
+  - `hasNoHooks: Boolean`
+  - `hideSystem: Boolean`
+  - `idIncludes: String`
+- `RunFilterInput`
+  - `nodeKinds`, `nodeIds`, `ok`, `parentIds`, `rootIds`, `correlationIds`
+- `LogFilterInput`
+  - `levels`, `messageIncludes`, `correlationIds`
+- `EmissionFilterInput`
+  - `eventIds`, `emitterIds`, `correlationIds`
+- `ErrorFilterInput`
+  - `sourceKinds`, `sourceIds`, `messageIncludes`, `correlationIds`
+
+## Mutation Root
+
+The current `Mutation` type exposes:
+
+- `swapTask(taskId: ID!, runCode: String!): SwapResult!`
+- `unswapTask(taskId: ID!): SwapResult!`
+- `unswapAllTasks: [SwapResult!]!`
+- `invokeTask(taskId: ID!, inputJson: String, pure: Boolean = false, evalInput: Boolean = false): InvokeResult!`
+- `invokeEvent(eventId: ID!, inputJson: String, evalInput: Boolean = false): InvokeEventResult!`
+- `editFile(path: String!, content: String!): EditFileResult!`
+- `eval(code: String!): EvalResult!`
+
+### Mutation Notes
+
+- `swapTask` replaces a task's `run()` implementation at runtime.
+- `invokeTask` supports `pure: true` to bypass middleware.
+- `editFile` accepts structured paths such as `workspace:src/index.ts`.
+- `eval` is guarded and disabled in production unless `RUNNER_DEV_EVAL=1`.
+
+## Core Types
+
+### BaseElement
+
+Shared across tasks, hooks, resources, middleware, events, tags, errors, and async contexts:
+
+- `id`
+- `meta`
+- `filePath`
+- `fileContents(startLine, endLine)`
+- `markdownDescription`
+- `isPrivate`
+- `visibilityReason`
+- `tags`
+- `tagsDetailed`
+
+Many concrete element types also expose:
+
+- `coverage`
+- `coverageContents`
+- `registeredBy`
+- resolved variants such as `registeredByResolved`
+
+### Task
+
+Key fields:
+
+- `dependsOn`, `dependsOnResolved`
+- `middleware`, `middlewareResolved`, `middlewareResolvedDetailed`
+- `emits`, `emitsResolved`
+- `inputSchema`, `inputSchemaReadable`
+- `rpcLane`
+- `interceptorCount`, `hasInterceptors`, `interceptorOwnerIds`
+- `runs(afterTimestamp, last, filter)`
+- `isDurable`, `durableResource`, `durableWorkflowKey`
+- `overriddenBy`, `registeredBy`
+
+The middleware usage objects now include subtree provenance details:
+
+- `TaskMiddlewareUsage.id`
+- `TaskMiddlewareUsage.config`
+- `TaskMiddlewareUsage.origin`
+- `TaskMiddlewareUsage.subtreeOwnerId`
+- `TaskMiddlewareUsage.node`
+
+### Hook
+
+Key fields:
+
+- `events`
+- `event` (deprecated singular form)
+- `hookOrder`
+- `dependsOn`, `depenendsOnResolved`
+- `middleware`, `middlewareResolvedDetailed`
+- `runs(...)`
+
+### Resource
+
+Key fields:
+
+- `dependsOn`, `dependsOnResolved`
+- `config`, `configSchema`, `configSchemaReadable`
+- `context`
+- `middleware`, `middlewareResolvedDetailed`
+- `overrides`, `overridesResolved`
+- `registers`, `registersResolved`
+- `usedBy`
+- `emits`
+- `registeredBy`, `registeredByResolved`
+- `hasCooldown`, `hasReady`, `hasHealthCheck`
+- `isolation`
+- `subtree`
+
+Important nested resource types:
+
+- `ResourceIsolation`
+  - `deny`
+  - `only`
+  - `whitelist`
+  - `exports`
+  - `exportsMode`
+- `ResourceSubtreePolicy`
+  - `tasks`
+  - `middleware`
+  - `resources`
+  - `hooks`
+  - `taskMiddleware`
+  - `resourceMiddleware`
+  - `events`
+  - `tags`
+
+Subtree policy now covers identity-aware summaries too:
+
+- `ResourceSubtreeTaskBranch.identity`
+- `ResourceSubtreeMiddlewareScope.identityScope`
+
+### Middleware
+
+The generic `Middleware` type exposes the combined view used by the introspector:
+
+- `autoApply`
+- `emits`
+- `configSchema`, `configSchemaReadable`
+- `usedByTasks`, `usedByTasksResolved`, `usedByTasksDetailed`
+- `usedByResources`, `usedByResourcesResolved`, `usedByResourcesDetailed`
+
+Specialized views:
+
+- `TaskMiddleware.usedBy`
+- `TaskMiddleware.usedByDetailed`
+- `ResourceMiddleware.usedBy`
+- `ResourceMiddleware.usedByDetailed`
+
+### Event
+
+Key fields:
+
+- `payloadSchema`, `payloadSchemaReadable`
+- `transactional`
+- `parallel`
+- `eventLane`
+- `rpcLane`
+- `emittedBy`, `emittedByResolved`
+- `listenedToBy`, `listenedToByResolved`
+- `registeredBy`, `registeredByResolved`
+
+### Tag
+
+Tags now fan out across the full model:
+
+- `configSchema`
+- `config`
+- `targets`
+- `tasks`
+- `hooks`
+- `resources`
+- `taskMiddlewares`
+- `resourceMiddlewares`
+- `events`
+- `errors`
+- `all`
+
+### Error
+
+Key fields:
+
+- `dataSchema`
+- `thrownBy`
+
+### AsyncContext
+
+Key fields:
+
+- `serialize`
+- `parse`
+- `usedBy`
+- `requiredBy`
+- `providedBy`
+
+### RunOptions
+
+Runner-dev now exposes effective startup/runtime settings through `runOptions`:
+
+- `mode`
+- `debug`, `debugMode`
+- `logsEnabled`, `logsPrintThreshold`, `logsPrintStrategy`, `logsBuffer`
+- `errorBoundary`
+- `shutdownHooks`
+- `dryRun`
+- `lazy`
+- `lifecycleMode`
+- `dispose`
+- `executionContext`
+- `hasOnUnhandledError`
+- `rootId`
+
+Nested types:
+
+- `RunDisposeOptions`
+  - `totalBudgetMs`
+  - `drainingBudgetMs`
+  - `cooldownWindowMs`
+- `RunExecutionContextOptions`
+  - `enabled`
+  - `cycleDetection`
+
+### InterceptorOwnersSnapshot
+
+Useful when debugging `taskDependency.intercept(...)` and middleware interceptors:
+
+- `tasksById`
+- `middleware.globalTaskInterceptorOwnerIds`
+- `middleware.globalResourceInterceptorOwnerIds`
+- `middleware.perTaskMiddlewareInterceptorOwnerIds`
+- `middleware.perResourceMiddlewareInterceptorOwnerIds`
+
+## Live Telemetry
+
+`live: Live!` exposes:
+
+- `memory: MemoryStats!`
+- `cpu: CpuStats!`
+- `eventLoop(reset: Boolean): EventLoopStats!`
+- `gc(windowMs: Float): GcStats!`
+- `logs(afterTimestamp, last, filter): [LogEntry!]!`
+- `emissions(afterTimestamp, last, filter): [EmissionEntry!]!`
+- `errors(afterTimestamp, last, filter): [ErrorEntry!]!`
+- `runs(afterTimestamp, last, filter): [RunRecord!]!`
+- `healthReport: ResourceHealthReport`
+
+Supporting types include:
+
+- `LogEntry`
+- `EmissionEntry`
+- `ErrorEntry`
+- `RunRecord`
+- `ResourceHealthReport`
+- `ResourceHealthTotals`
+- `ResourceHealthEntry`
+
+## Diagnostics And Swap Types
+
+- `Diagnostic`
+  - `severity`
+  - `code`
+  - `message`
+  - `nodeId`
+  - `nodeKind`
+- `SwapResult`
+- `SwappedTask`
+- `InvokeResult`
+- `InvokeEventResult`
+- `EvalResult`
+- `EditFileResult`
+
+## Enums Worth Knowing
+
+- `LogLevelEnum`
+  - `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `log`
+- `SourceKindEnum`
+  - `TASK`, `HOOK`, `RESOURCE`, `MIDDLEWARE`, `INTERNAL`
+- `NodeKindEnum`
+  - `TASK`, `HOOK`
+- `MiddlewareApplyScope`
+  - `WHERE_VISIBLE`, `SUBTREE`
+- `IsolationExportsMode`
+  - `UNSET`, `NONE`, `LIST`
+- `TagTarget`
+  - `TASKS`, `RESOURCES`, `EVENTS`, `HOOKS`, `TASK_MIDDLEWARES`, `RESOURCE_MIDDLEWARES`, `ERRORS`
+- `ResourceHealthStatus`
+  - `healthy`, `degraded`, `unhealthy`
+
+## SDL Regeneration
+
+When this file drifts, regenerate your view from the actual schema rather than hand-guessing:
+
+```bash
+runner-dev schema sdl --endpoint http://localhost:1337/graphql
+```
+
+Or from the repo without a running server:
+
+```bash
+runner-dev schema sdl --entry-file src/main.ts
+```

package/readmes/COMPACT_GUIDE.md

@@ -0,0 +1,254 @@
+# Runner-Dev Compact Guide
+
+Runner-Dev is the developer-facing toolkit for inspecting, querying, and debugging Runner apps through a docs UI, GraphQL endpoint, MCP server, live telemetry, and controlled hot-swapping. Use it when the task is about what a Runner app looks like at runtime, what the docs/AI layer sees, or how runner-dev exposes that information.
+
+It also supports a static export path through `exportDocs(app, { output?, overwrite? })` when you want the visual catalog without keeping a live server around.
+
+## Use This When
+
+- The task touches `/docs/data`, docs UI, chat context, agent-facing documentation, or the topology graph / blast-radius / mindmap views.
+- You need GraphQL or MCP access to runtime topology, telemetry, schema, or diagnostics.
+- You are debugging telemetry, live events, durable metadata, hook targets, or lane surfaces.
+- You are changing runner-dev CLI, MCP tools, docs payload shaping, or introspection behavior.
+
+## Fastest Path To Success
+
+1. Decide whether the target app is already running.
+2. If it is running, prefer MCP or GraphQL before reading lots of source.
+3. If it is package work, locate the subsystem first:
+   - docs payloads and docs UI
+   - introspector/store serialization
+   - MCP tools
+   - live telemetry
+   - swap/hot-reload
+4. Patch the smallest surface that explains the behavior.
+5. Run the narrowest relevant test first, then widen only if needed.
+
+## Quick Setup
+
+Register runner-dev in the Runner root:
+
+```ts
+import { r } from "@bluelibs/runner";
+import { dev } from "@bluelibs/runner-dev";
+
+export const app = r
+  .resource("app")
+  .register([
+    dev.with({
+      port: 1337,
+      maxEntries: 1000,
+    }),
+  ])
+  .build();
+```
+
+Expected endpoints after the app starts:
+
+- UI: `http://localhost:1337`
+- GraphQL: `http://localhost:1337/graphql`
+- Live stream: `http://localhost:1337/live/stream`
+- Docs payload: `http://localhost:1337/docs/data`
+
+Static export option:
+
+```ts
+// scripts/export-docs.ts
+import { exportDocs } from "@bluelibs/runner-dev";
+import { app } from "../src/app";
+
+await exportDocs(app);
+// Optional custom destination:
+await exportDocs(app, {
+  output: "./artifacts/runner-dev-catalog",
+  overwrite: true,
+});
+```
+
+Add a package script:
+
+```json
+{
+  "scripts": {
+    "docs:export": "tsx scripts/export-docs.ts"
+  }
+}
+```
+
+Then run:
+
+```bash
+npm run docs:export
+```
+
+Notes:
+
+- default output is `./runner-dev-catalog`
+- `exportDocs()` uses Runner dry-run under the hood: it effectively does `run(app, { dryRun: true })` and snapshots the composed in-memory store
+- `exportDocs(app)` writes a standalone `index.html` plus `snapshot.json`
+- custom non-empty directories require `overwrite: true`
+- the exported `index.html` is standalone and can be opened directly over `file://`
+- `snapshot.json` is still written as an auxiliary artifact for inspection, debugging, and snapshot-backed MCP
+- this works well in CI too: upload the export folder as a build artifact and inspect it after the pipeline finishes
+- in this repository, `npm run play:export` is the same pattern wired to the reference commerce app used by `npm run play`
+
+## MCP Quickstart
+
+Use MCP against either a live Dev GraphQL endpoint or an exported `snapshot.json`.
+
+Minimal client config:
+
+```json
+{
+  "mcpServers": {
+    "runner-dev": {
+      "command": "npx",
+      "args": ["@bluelibs/runner-dev", "mcp"],
+      "env": {
+        "ENDPOINT": "http://localhost:1337/graphql",
+        "ALLOW_MUTATIONS": "false"
+      }
+    }
+  }
+}
+```
+
+Authenticated variant:
+
+```json
+{
+  "mcpServers": {
+    "runner-dev": {
+      "command": "npx",
+      "args": ["@bluelibs/runner-dev", "mcp"],
+      "env": {
+        "ENDPOINT": "http://localhost:1337/graphql",
+        "HEADERS": "{\"Authorization\":\"Bearer <token>\"}",
+        "ALLOW_MUTATIONS": "false"
+      }
+    }
+  }
+}
+```
+
+Direct launch:
+
+```bash
+ENDPOINT=http://localhost:1337/graphql npx -y @bluelibs/runner-dev mcp
+SNAPSHOT_FILE=./runner-dev-catalog/snapshot.json npx -y @bluelibs/runner-dev mcp
+```
+
+First checks, in order:
+
+1. `graphql.ping`
+2. `project.overview`
+3. `graphql.query`
+
+Shell equivalents:
+
+```bash
+ENDPOINT=http://localhost:1337/graphql npx @bluelibs/runner-dev ping
+ENDPOINT=http://localhost:1337/graphql npx @bluelibs/runner-dev overview --details 5
+ENDPOINT=http://localhost:1337/graphql npx @bluelibs/runner-dev query 'query { tasks { id } resources { id } }' --format pretty
+```
+
+Notes:
+
+- Keep `ALLOW_MUTATIONS=false` unless you intentionally need write access.
+- Set `HEADERS` if the GraphQL endpoint requires auth.
+- `SNAPSHOT_FILE` enables read-only MCP over an exported catalog without starting the app.
+- If `graphql.ping` fails, check that the app is running, the port is correct, and `HEADERS` is valid JSON.
+
+## First Things To Inspect
+
+If the app is running:
+
+- Start from `/docs/data` when the question is about what the docs UI or AI sees.
+- Use `project.overview` for a fast topology summary.
+- Use GraphQL for focused reads, not giant dumps.
+- Use live telemetry only with narrow limits such as `last: 10`.
+
+Minimal topology query:
+
+```graphql
+query FirstLook {
+  tasks {
+    id
+  }
+  resources {
+    id
+  }
+  hooks {
+    id
+  }
+  diagnostics {
+    severity
+    code
+    message
+  }
+}
+```
+
+Minimal live query:
+
+```graphql
+query LiveFirstLook {
+  live {
+    logs(last: 10) {
+      level
+      message
+      correlationId
+    }
+    errors(last: 10) {
+      sourceKind
+      message
+      correlationId
+    }
+  }
+}
+```
+
+## High-Value Source Files
+
+When working inside `@bluelibs/runner-dev`, start here:
+
+- `src/resources/routeHandlers/getDocsData.ts` for docs payloads and bundled context
+- `src/resources/models/Introspector.ts` and related store initialization for topology
+- `src/mcp/tools/*` for MCP help/query behavior
+- `src/resources/live.resource.ts` and telemetry resources for live data
+- `src/ui/src/components/Documentation/*` for docs/chat UI behavior
+- `src/ui/src/components/Documentation/components/TopologyPanel.tsx` and `src/ui/src/components/Documentation/utils/topologyGraph.ts` for topology graph projections and rendering
+- `src/resources/swap.resource.ts` and `src/resources/swap.tools.ts` for hot-swapping surfaces
+
+## Core Surfaces
+
+- Docs UI: the browser surface for architecture, live data, and AI assistance
+- Topology graph: a focused lens for blast-radius analysis and resource mindmaps
+- `/docs/data`: the JSON payload feeding docs UI and in-app AI context
+- GraphQL: the main runtime introspection surface
+- MCP: the fastest AI-native access path when the app is already running
+- Live telemetry: logs, emissions, errors, runs, and correlation-driven inspection
+- Swap tooling: controlled runtime task replacement and restoration
+
+## Current Compatibility Notes
+
+Assume current Runner reality, not old examples:
+
+- Identity moved from `asyncContexts.tenant` to `asyncContexts.identity`; related middleware uses `identityScope`.
+- Hook targets may come from selectors such as `subtreeOf(...)` or predicates, not only raw `hook.on`.
+- Event Lane routing comes from `r.eventLane(...).applyTo([...])`, not old lane-tag assumptions.
+- Runner supports `run(app, { signal })`, `run(app, { identity })`, and `runtime.dispose({ force: true })`.
+
+## AI Working Strategy
+
+- Use the Runner skill for framework design or core Runner contracts.
+- Use runner-dev context for tooling behavior, docs payloads, MCP, GraphQL, telemetry, and UI integration.
+- Prefer focused tests first: `npm run test -- docs.data`, `npm run test -- mcp`, `npm run test -- live`, or another narrow suite near the touched surface.
+- Use `pure: true` when validating swapped task behavior safely.
+- Avoid huge live queries, broad schema dumps, or mutation access unless the task truly needs them.
+
+## Go Deeper
+
+- Read `README.md` for installation, CLI, and broader examples.
+- Read the Runner skill for framework-level architecture and contracts.
+- Read source near the touched surface before broadening to unrelated subsystems.