Ship PerpScope v2.0 terminal integration kit

Author: Clay

README.md

@@ -20,17 +20,17 @@ Live demo: [williamclay8.github.io/perpscope](https://williamclay8.github.io/per
 ```
 
 ```js
+import { summarizePerpScopeExport } from "@perpscope/percolator-adapter";
+
 const response = await fetch("https://raw.githubusercontent.com/williamclay8/perpscope/main/examples/perpscope-export.sample.json");
 const payload = await response.json();
 
 if (payload.schema !== "perpscope.export.v1") throw new Error("Unexpected export schema");
 
-const market = payload.market.name;
-const heat = payload.radar.rows[0].scoreLabel;
-const reasons = payload.market.whyHot.reasons;
+const summary = summarizePerpScopeExport(payload);
 ```
 
-Use `docs/embed-integration.md` for the copy-paste guide and `examples/embed-consumer/` for a tiny iframe plus JSON parser example.
+Use `docs/embed-integration.md` for the copy-paste guide, `examples/copy-integration/` for a live copy page, and `examples/embed-consumer/` for the terminal side-rail mock.
 
 ## 2-Minute Terminal Builder Check
 
@@ -182,6 +182,7 @@ examples/percolator-mainnet-sol.readonly-rpc.json
 examples/percolator-devnet-wif.readonly-rpc.json
 examples/funding-skew-history.stdout.json
 examples/adapter-consumer/
+examples/copy-integration/
 examples/embed-consumer/
 examples/perpscope-export.sample.json
 examples/terminal-recipes.json
@@ -249,6 +250,7 @@ schemas/perpscope-snapshot.schema.json
 schemas/percolator-cli-bundle.schema.json
 schemas/read-only-rpc-fetch.schema.json
 schemas/funding-skew-history.schema.json
+schemas/perpscope-export.schema.json
 ```
 
 The source-backed adapter field map lives in `docs/field-compatibility-map.md`, with a JSON manifest at `examples/field-compatibility-map.json`, an export artifact at `examples/compatibility-report-export.json`, a diff artifact at `examples/compatibility-diff.json`, and fixture packs such as `examples/fixture-pack-drifted-aliases.json`, `examples/fixture-pack-real-sanitized-rpc-shape.json`, and `examples/static-real-snapshot.json`.
@@ -269,6 +271,8 @@ import {
   compareCompatibilityReports,
   normalizeFundingSkewHistory,
   normalizePercolatorSnapshot,
+  parsePerpScopeExport,
+  summarizePerpScopeExport,
   simulatePriceShock
 } from "./packages/percolator-adapter/index.js";
 
@@ -280,6 +284,7 @@ const reality = buildCompatibilityRealityCheck(compatibility, { input: decodedJs
 const drift = compareCompatibilityReports(previousCompatibility, compatibility);
 const watchtower = buildWatchtowerSignals(market, stress);
 const carryHistory = normalizeFundingSkewHistory(market.history.fundingSkew, market);
+const embedSummary = summarizePerpScopeExport(parsePerpScopeExport(perpscopeExportJson));
 ```
 
 The package is intentionally side-effect free. It does not create wallets, sign, send, route, or submit transactions.
@@ -423,6 +428,7 @@ The normalized market DTO includes:
 - `docs/release-v1.7.0.md` mirrors the public release notes for why-hot explanations, feed health, share links, and adapter targets.
 - `docs/release-v1.8.0.md` mirrors the public release notes for exportable JSON and embed widgets.
 - `docs/release-v1.9.0.md` mirrors the public release notes for copy-paste embeds and export consumer examples.
+- `docs/release-v2.0.0.md` mirrors the public release notes for the schema-locked terminal integration kit.
 - `docs/adapter-targets.md` documents the terminal rail, risk overlay, execution lane, feed monitor, and embed contracts.
 - `docs/embed-integration.md` documents iframe widgets, the export fixture, and trusted display fields.
 - `docs/decoded-live-source.md` documents the CORS endpoint contract for decoded Percolator live feeds.
@@ -466,7 +472,7 @@ Current public site: [williamclay8.github.io/perpscope](https://williamclay8.git
 
 - v0.4 shipped: capture intake for pasted/dropped decoded outputs, compatibility scoring, missing-field warnings, and ignored-field mapping.
 - v0.4 follow-up: field-level compatibility map for terminal import/export adapters.
-- npm package shipped: `@perpscope/percolator-adapter@1.1.0`.
+- npm package shipped: `@perpscope/percolator-adapter@2.0.0`.
 - v0.5 shipped: downloadable compatibility report export for terminal builders.
 - v0.6 shipped: compatibility diffing and alias suggestions for drifting terminal shapes.
 - v0.7 shipped: local compatibility workbench, CLI report/diff commands, and fixture packs.

docs/embed-integration.md

@@ -33,6 +33,8 @@ PerpScope gives terminal builders two read-only integration paths:
 `examples/perpscope-export.sample.json` is a stable fixture for wiring parsers and visual mocks before a terminal has live decoded output.
 
 ```js
+import { summarizePerpScopeExport } from "@perpscope/percolator-adapter";
+
 const response = await fetch(
   "https://raw.githubusercontent.com/williamclay8/perpscope/main/examples/perpscope-export.sample.json"
 );
@@ -42,26 +44,7 @@ if (payload.schema !== "perpscope.export.v1") {
   throw new Error("Unexpected PerpScope export schema.");
 }
 
-const feedItems = new Map(payload.feedHealth.items.map((item) => [item.label, item.value]));
-const topMarket = payload.radar.rows[0];
-const reasons = payload.market.whyHot.reasons.map((reason) => ({
-  label: reason.label,
-  value: reason.value,
-  tone: reason.tone
-}));
-
-console.log({
-  market: payload.market.name,
-  heat: topMarket.scoreLabel,
-  feed: {
-    markets: feedItems.get("markets"),
-    slot: feedItems.get("slot"),
-    unitChecks: feedItems.get("unit checks"),
-    gaps: feedItems.get("gaps")
-  },
-  reasons,
-  readOnly: payload.safety
-});
+console.log(summarizePerpScopeExport(payload));
 ```
 
 Live decoded protocol snapshots are available from the hosted decoder worker:
@@ -76,6 +59,28 @@ const decodedSnapshot = await response.json();
 
 Use the PerpScope app or `@perpscope/percolator-adapter` to normalize decoded snapshots into the cockpit DTOs.
 
+## Terminal Integration Kit
+
+```bash
+npm install @perpscope/percolator-adapter
+```
+
+```js
+import {
+  parsePerpScopeExport,
+  rankRadarRows,
+  summarizeFeedHealth,
+  summarizePerpScopeExport
+} from "@perpscope/percolator-adapter";
+
+const exportPayload = parsePerpScopeExport(payload);
+const summary = summarizePerpScopeExport(exportPayload);
+const feed = summarizeFeedHealth(exportPayload);
+const hottest = rankRadarRows(exportPayload)[0];
+```
+
+The schema is published at `schemas/perpscope-export.schema.json`.
+
 ## Fields To Trust
 
 Treat these as stable display inputs for terminal surfaces:

docs/field-compatibility-map.md

@@ -1,6 +1,6 @@
 # PerpScope Field Compatibility Map
 
-This map is the v1.1.0 implementation contract for terminal builders sending read-only Percolator-like output into PerpScope. It is source-grounded in:
+This map is the v2.0.0 implementation contract for terminal builders sending read-only Percolator-like output into PerpScope. It is source-grounded in:
 
 - `src/lib/percolator-adapter.js`
 - `src/lib/watchtower-signals.js`

docs/release-v2.0.0.md

@@ -0,0 +1,26 @@
+# PerpScope v2.0.0
+
+PerpScope v2.0 turns the embed layer into a schema-locked terminal integration kit.
+
+## Shipped
+
+- Adds `schemas/perpscope-export.schema.json` for the `perpscope.export.v1` contract.
+- Adds package helpers: `parsePerpScopeExport()`, `summarizePerpScopeExport()`, `summarizeFeedHealth()`, and `rankRadarRows()`.
+- Adds `examples/copy-integration/`, a live copy page for iframe snippets, npm parser imports, schema links, and terminal placement.
+- Updates `examples/embed-consumer/` into a richer terminal side-rail mock that consumes the same export contract.
+- Bumps the app export and `@perpscope/percolator-adapter` package surfaces to `2.0.0`.
+- Documents the install-and-embed path in the README and `docs/embed-integration.md`.
+
+## Safety
+
+The v2.0 integration kit remains read-only. The schema requires `wallet`, `signer`, `transaction`, and `orderRouting` to be false, and the helpers reject exports that do not declare that safety boundary.
+
+## Live
+
+```text
+https://williamclay8.github.io/perpscope/
+https://williamclay8.github.io/perpscope/examples/copy-integration/
+https://williamclay8.github.io/perpscope/examples/embed-consumer/
+https://williamclay8.github.io/perpscope/examples/perpscope-export.sample.json
+https://williamclay8.github.io/perpscope/schemas/perpscope-export.schema.json
+```

examples/adapter-consumer/README.md

@@ -25,7 +25,7 @@ npm install @perpscope/percolator-adapter
 or use a version range:
 
 ```json
-"@perpscope/percolator-adapter": "^1.1.0"
+"@perpscope/percolator-adapter": "^2.0.0"
 ```
 
 The example stays read-only. It does not connect wallets, sign, send, route, place orders, or submit transactions.

examples/compatibility-diff.json

@@ -3,7 +3,7 @@
   "version": 1,
   "package": {
     "name": "@perpscope/percolator-adapter",
-    "version": "1.1.0"
+    "version": "2.0.0"
   },
   "generatedAt": "2026-06-21T00:00:00.000Z",
   "tone": "danger",

examples/compatibility-report-export.json

@@ -3,7 +3,7 @@
   "version": 1,
   "package": {
     "name": "@perpscope/percolator-adapter",
-    "version": "1.1.0"
+    "version": "2.0.0"
   },
   "generatedAt": "2026-06-21T00:00:00.000Z",
   "safety": {

examples/copy-integration/README.md

@@ -0,0 +1,10 @@
+# Copy Integration Example
+
+This page is the fast path for adding PerpScope to another terminal:
+
+- iframe snippets for `?embed=radar`
+- npm parser helpers from `@perpscope/percolator-adapter`
+- schema and fixture links for `perpscope.export.v1`
+- a placement map for rails, market drawers, and feed footers
+
+Run the site and open `http://127.0.0.1:4173/examples/copy-integration/`.