@moonan_ai/sdk 0.0.0-stage → 0.0.4-alpha2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pheobe-Southwood
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,71 @@
-# Temporary Holding Version
+# @moonan_ai/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Moonan 插件 SDK：契约、注册表与浏览器钩子。写 Moonan 插件只需要这一个包——Chord 的原语
+（`remote`、`local`、`method`、`hostNamed`、`defineFacet`、`defineRegistry`）由它再导出。
+
+Moonan 是一个本地运行的插件工作台：平台只提供宿主、端口、插件发现与切面装载，所有功能——包括
+AI 对话——都是插件。
+
+```bash
+npm i @moonan_ai/sdk
+```
+
+## 两个入口
+
+| 入口 | 给谁用 |
+|---|---|
+| `@moonan_ai/sdk` | 服务端切面、以及需要契约/注册表的浏览器代码 |
+| `@moonan_ai/sdk/web` | 浏览器切面：`Panels`、`useRemote`、`useReadable`、`useRefStatus` |
+
+浏览器切面不要自行打包 React、Chord 或本包：外壳的 import map 已经提供了它们，而且只有一份。
+
+## 服务端切面
+
+```js
+import { Type, defineFacet, hostNamed, method, remote } from "@moonan_ai/sdk";
+
+const Counter = remote("example.counter", {
+	version: 1,
+	input: Type.Object({}),
+	host: hostNamed("moonan"),
+	variants: { v1: { state: { n: Type.Number() }, methods: { bump: method() } } },
+});
+
+export default defineFacet((api) => {
+	api.serve(Counter, (_input, _principal, self) => {
+		const n = self.state("n", Type.Number(), 0);
+		return { variant: "v1", n, bump: (ctx) => n.change(ctx, (value) => value + 1) };
+	});
+});
+```
+
+## 浏览器切面
+
+```js
+import { Panels } from "@moonan_ai/sdk/web";
+import { Type, defineFacet, local, method } from "@moonan_ai/sdk";
+import { createElement as h } from "react";
+
+const Root = local("example.counter.web", { version: 1, input: Type.Object({}), members: { noop: method() } });
+
+export default defineFacet((api) => {
+	api.serve(Root, (_input, _p, self) => {
+		self.register(Panels, { counter: { id: "counter", title: "Counter", order: 10, component: () => h("div") } });
+		return { noop: () => undefined };
+	}, { lifetime: "host" });
+});
+```
+
+## 约定
+
+- 契约在两端**各写一份**：Chord 认指纹（名字、版本、成员、类型住在哪个宿主），不认模块实例。
+- 注册表贡献（`Routes`、`Panels`）必须来自 `{ lifetime: "host" }` 的对象。
+- 服务端宿主名固定为 `"moonan"`；写别的名字，`api.serve` 会当场拒绝。
+- 浏览器切面是**单个 ESM 文件**：浏览器没有模块 hook，重载只换入口。
+
+完整写法：<https://github.com/Pheobe-Southwood/Moonan/blob/main/docs/plugins.md> ·
+词汇表：<https://github.com/Pheobe-Southwood/Moonan/blob/main/CONTEXT.md>
+
+## 许可
+
+MIT

package/dist/index.js

@@ -0,0 +1,17 @@
+/**
+ * `@moonan_ai/sdk` — everything a plugin needs on either side of the wire.
+ *
+ * The root entry is shared by the server facet and the browser facet: contracts,
+ * registries and the Chord primitives they are built from. Browser-only surface (the
+ * `Panels` registry and the React hooks) lives in `@moonan_ai/sdk/web`, because it needs
+ * React and the root entry must stay importable from a Node facet.
+ */
+export { Manifest, FacetSetSchema, WebFacetSchema, } from "./manifest.js";
+export { Routes } from "./routes.js";
+/** Chord primitives, re-exported so a plugin needs two dependencies instead of three. */
+export { ChordError, defineFacet, defineRegistry, forbidden, hostFamily, hostNamed, invalid, isChordError, local, method, opaque, remote, } from "@earendil-works/chord";
+/** Explicit cancellation/context helpers; browser-safe, same entry points as chord. */
+export { BACKGROUND_CONTEXT, awaitWithContext, traceIn, withAbortSignal, withCancel, withoutAbortSignal, } from "@earendil-works/chord/context";
+/** The schema builder every contract is written with. */
+export { Type } from "typebox";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACN,QAAQ,EACR,cAAc,EACd,cAAc,GAGd,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,MAAM,EAAqB,MAAM,aAAa,CAAC;AAExD,yFAAyF;AACzF,OAAO,EACN,UAAU,EACV,WAAW,EACX,cAAc,EACd,SAAS,EACT,UAAU,EACV,SAAS,EACT,OAAO,EACP,YAAY,EACZ,KAAK,EACL,MAAM,EACN,MAAM,EACN,MAAM,GAiBN,MAAM,uBAAuB,CAAC;AAE/B,uFAAuF;AACvF,OAAO,EACN,kBAAkB,EAClB,gBAAgB,EAChB,OAAO,EACP,eAAe,EACf,UAAU,EACV,kBAAkB,GAElB,MAAM,+BAA+B,CAAC;AAEvC,yDAAyD;AACzD,OAAO,EAAE,IAAI,EAA6B,MAAM,SAAS,CAAC"}

package/dist/manifest.js

@@ -0,0 +1,66 @@
+import { hostNamed, remote } from "@earendil-works/chord";
+import { Type } from "typebox";
+/**
+ * A browser facet: the module URL and a hash of its exact file contents.
+ *
+ * The URL alone cannot tell a client that the file changed; a server reload with the same
+ * path would otherwise look identical. The hash is what makes a browser reload only when
+ * its web code actually changed.
+ */
+export const WebFacetSchema = Type.Object({
+    /** Absolute path on this server (`/facets/<key>/web.js`). */
+    url: Type.String(),
+    /** SHA-256 of the file contents, truncated for display. */
+    hash: Type.String(),
+});
+/**
+ * One plugin's facets, as the browser needs to know them.
+ *
+ * `name` is a display label derived from the directory or package; it is not an identity.
+ * The runtime identity of a facet is its module URL. A server-only plugin has no `web`, and
+ * a plugin that failed to resolve carries `error` instead — the browser still receives it,
+ * so the shell can report the failure rather than show a silently missing tab.
+ */
+export const FacetSetSchema = Type.Object({
+    name: Type.String(),
+    version: Type.String(),
+    /** Where the facets came from: an installed package, or a directory on disk. */
+    source: Type.Union([Type.Literal("package"), Type.Literal("directory")]),
+    web: Type.Optional(WebFacetSchema),
+    error: Type.Optional(Type.String()),
+});
+/**
+ * The only object the platform publishes: which browser facets the browser host must load.
+ *
+ * This is the seam that keeps the platform free of feature state. The loader knows which
+ * modules exist; the browser cannot find that out alone (it has no filesystem and no
+ * registry to ask), so exactly one read-only object carries it across. Chord names a
+ * server `Manifest` object as how browsers learn of changes (spec §6); the particular
+ * fields here are Moonan application state, not protocol fields.
+ *
+ * Contract version 3 changed `web` from a bare URL string to `{ url, hash }`. There is no
+ * compatibility adapter: a browser is mapped to `upgrade_required` and must load the new
+ * shell (a non-client consumer gets `contract_mismatch`).
+ */
+export const Manifest = remote("moonan.manifest", {
+    version: 3,
+    input: Type.Object({}),
+    host: hostNamed("moonan"),
+    variants: {
+        v1: {
+            state: {
+                /** The platform's own version, so a client can tell which build it is talking to. */
+                version: Type.String(),
+                facets: Type.Array(FacetSetSchema),
+                /**
+                 * chord's code version (`host.codeVersion`): 1 at startup, one higher after every
+                 * reload that committed. This is Moonan application state, not chord's removed
+                 * `Shape.codeVersion`; a browser decides whether to reload from each `web.hash`,
+                 * and never from this number as a protocol value.
+                 */
+                revision: Type.Number(),
+            },
+        },
+    },
+});
+//# sourceMappingURL=manifest.js.map

package/dist/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,IAAI,EAAe,MAAM,SAAS,CAAC;AAE5C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,CAAC,MAAM,CAAC;IACzC,6DAA6D;IAC7D,GAAG,EAAE,IAAI,CAAC,MAAM,EAAE;IAClB,2DAA2D;IAC3D,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE;CACnB,CAAC,CAAC;AAGH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,CAAC,MAAM,CAAC;IACzC,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE;IACnB,OAAO,EAAE,IAAI,CAAC,MAAM,EAAE;IACtB,gFAAgF;IAChF,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;IACxE,GAAG,EAAE,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC;IAClC,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;CACnC,CAAC,CAAC;AAGH;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAC,iBAAiB,EAAE;IACjD,OAAO,EAAE,CAAC;IACV,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;IACtB,IAAI,EAAE,SAAS,CAAC,QAAQ,CAAC;IACzB,QAAQ,EAAE;QACT,EAAE,EAAE;YACH,KAAK,EAAE;gBACN,qFAAqF;gBACrF,OAAO,EAAE,IAAI,CAAC,MAAM,EAAE;gBACtB,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC;gBAClC;;;;;mBAKG;gBACH,QAAQ,EAAE,IAAI,CAAC,MAAM,EAAE;aACvB;SACD;KACD;CACD,CAAC,CAAC"}

package/dist/routes.js

@@ -0,0 +1,11 @@
+import { defineRegistry } from "@earendil-works/chord";
+/**
+ * The server-side way out of the object protocol.
+ *
+ * Chord covers everything object-to-object; it has no opinion about plain HTTP, and the
+ * platform serves exactly one port for both. This registry is the hook between them:
+ * the keys are `"GET /path"` for one method, or `"/path"` for any. A request that matches
+ * nothing falls through to the built-in endpoints, the facet assets and the shell.
+ */
+export const Routes = defineRegistry("moonan.routes", { conflict: "error" });
+//# sourceMappingURL=routes.js.map

package/dist/routes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.js","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAcvD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,cAAc,CAAe,eAAe,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC"}

package/dist/web.js

@@ -0,0 +1,174 @@
+import { defineRegistry, isChordError, } from "@earendil-works/chord";
+import { useEffect, useLayoutEffect, useRef, useState } from "react";
+export { isChordError } from "@earendil-works/chord";
+/**
+ * A `gone` error that no new reference can fix: the consumer was built against a contract the
+ * provider no longer covers. For the shell's own contracts (the platform `Manifest`, or a
+ * protocol mismatch) the page needs the new build. For a plugin's contract, chord's remedy is
+ * to reload the web facets; the shell does that when the manifest reports changed facets.
+ */
+export function isFatalContractError(error) {
+    return isChordError(error, "contract_mismatch") || isChordError(error, "upgrade_required");
+}
+/**
+ * The browser-side way into the shell's navigation.
+ *
+ * Chord registries are per host, and a panel component cannot cross the wire, so the
+ * registry lives in the browser host and is filled by the plugin's own browser facet.
+ * The shell subscribes and renders; it never imports a panel.
+ */
+export const Panels = defineRegistry("moonan.panels", { conflict: "error" });
+/**
+ * Reads a state member, falling back while it has no value yet.
+ *
+ * `hold` returns before the object is live, and chord reports that as `not_ready` when the
+ * member is read — a transition, not a failure. `not_in_variant` is the other expected one:
+ * the provider's variant does not carry this member. Anything else is a bug in the read
+ * path and is reported rather than hidden behind the fallback.
+ */
+function readOr(readable, fallback) {
+    if (!readable)
+        return fallback;
+    try {
+        return readable.value;
+    }
+    catch (error) {
+        if (isChordError(error, "not_ready") || isChordError(error, "not_in_variant"))
+            return fallback;
+        console.error("[chord] reading state failed", error);
+        return fallback;
+    }
+}
+/**
+ * Acquires a reference from the browser host with `host.hold`.
+ *
+ * `hold` is the API chord designates for UI runtimes: synchronous, possibly still
+ * `loading`, and re-held by the runtime itself when the link comes back, so a reconnect
+ * costs no new reference. It is acquired in a layout effect rather than during render:
+ * that keeps the impossible-to-render intermediate commit off the screen, and makes the
+ * acquire/release pair symmetrical under StrictMode's mount → unmount → mount (a
+ * reference taken during render would leak the discarded one).
+ */
+export function useRemote(host, contract, input, options = {}) {
+    // The input is a plain JSON address, and a panel commonly passes a fresh `{}` each
+    // render. Key on its content so identity churn does not re-acquire the reference.
+    const key = JSON.stringify(input);
+    const [ref, setRef] = useState(null);
+    const [attempt, setAttempt] = useState(0);
+    const retries = useRef(0);
+    const fatalReported = useRef(false);
+    const warned = useRef(false);
+    const onFatal = useRef(options.onFatal);
+    onFatal.current = options.onFatal;
+    useLayoutEffect(() => {
+        if (!host) {
+            setRef(null);
+            return;
+        }
+        let held;
+        try {
+            held = host.hold(contract, JSON.parse(key));
+        }
+        catch (error) {
+            // A type this host cannot place (an unknown name, a local type it does not serve).
+            console.error("[chord] hold failed", error);
+            setRef(null);
+            return;
+        }
+        setRef(held);
+        return () => {
+            setRef(null);
+            held.release();
+        };
+    }, [host, contract, key, attempt]);
+    useEffect(() => {
+        if (!ref)
+            return;
+        return ref.onStatus((status, error) => {
+            // A reconnect re-holds in place (`loading`, last values readable) and needs nothing.
+            // `gone` is terminal for this reference — the object was forced away while held —
+            // and chord's guidance for a UI is to take a new one. Bounded, so a provider that
+            // keeps answering `gone` cannot spin the page.
+            if (status === "live") {
+                retries.current = 0;
+                fatalReported.current = false;
+                warned.current = false;
+                return;
+            }
+            if (status !== "gone")
+                return;
+            // A contract that the provider no longer covers cannot be fixed by taking another
+            // reference. The shell owns the official remedy (reload the web facets when the
+            // manifest reports changed facets); a panel only reports it upward, and without an
+            // `onFatal` handler it says once what the developer can do.
+            if (isFatalContractError(error)) {
+                const handler = onFatal.current;
+                if (handler !== undefined) {
+                    if (!fatalReported.current) {
+                        fatalReported.current = true;
+                        handler(error);
+                    }
+                    return;
+                }
+                if (!warned.current) {
+                    warned.current = true;
+                    console.warn("[chord] a reference is gone because its contract no longer binds. The shell reloads web facets when the Manifest reports changed facets; if this persists, the plugin's web code and contract are out of sync.", error);
+                }
+                return;
+            }
+            if (retries.current < 3) {
+                retries.current += 1;
+                setAttempt((value) => value + 1);
+                return;
+            }
+            if (!fatalReported.current) {
+                fatalReported.current = true;
+                onFatal.current?.(error);
+            }
+        });
+    }, [ref]);
+    return ref;
+}
+/**
+ * Follows a reference's status: `loading | live | released | gone`.
+ *
+ * `hold` returns before the object is live, so a panel renders from this instead of
+ * guessing. `gone` is the state that needs a new reference — a forced disposal, a host
+ * that closed, a contract the provider no longer serves.
+ */
+export function useRefStatus(ref) {
+    const [status, setStatus] = useState(() => ref?.status ?? null);
+    // Layout effect: the reference is acquired in one, and this is what turns that commit
+    // into a painted one. With a passive effect the first paint would still say "loading".
+    useLayoutEffect(() => {
+        if (!ref) {
+            setStatus(null);
+            return;
+        }
+        setStatus(ref.status);
+        return ref.onStatus((next) => setStatus(next));
+    }, [ref]);
+    return status;
+}
+/** Renders the current value of a chord `Readable`, and every later one. */
+export function useReadable(readable, fallback) {
+    const [value, setValue] = useState(() => readOr(readable, fallback));
+    useLayoutEffect(() => {
+        if (!readable) {
+            setValue(fallback);
+            return;
+        }
+        let cancelled = false;
+        setValue(readOr(readable, fallback));
+        const stop = readable.subscribe((next) => {
+            if (!cancelled)
+                setValue(next);
+        });
+        return () => {
+            cancelled = true;
+            stop();
+        };
+    }, [readable]);
+    return value;
+}
+//# sourceMappingURL=web.js.map

package/dist/web.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web.js","sourceRoot":"","sources":["../src/web.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@moonan_ai/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.4-alpha2",
+  "description": "Moonan plugin SDK: contracts, registries and browser hooks for plugin authors.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Pheobe-Southwood/Moonan.git",
+    "directory": "packages/sdk"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "development": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./web": {
+      "types": "./src/web.ts",
+      "development": "./src/web.ts",
+      "default": "./dist/web.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@earendil-works/chord": "1.4.0",
+    "typebox": "1.3.27"
+  },
+  "peerDependencies": {
+    "react": ">=19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "@types/react": "^19.3.0",
+    "react": "^19.3.1"
+  },
+  "keywords": [
+    "moonan",
+    "plugin",
+    "chord",
+    "sdk"
+  ],
+  "homepage": "https://github.com/Pheobe-Southwood/Moonan#readme",
+  "bugs": {
+    "url": "https://github.com/Pheobe-Southwood/Moonan/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "build": "tsc -p tsconfig.build.json"
+  }
 }

package/src/index.ts

@@ -0,0 +1,62 @@
+/**
+ * `@moonan_ai/sdk` — everything a plugin needs on either side of the wire.
+ *
+ * The root entry is shared by the server facet and the browser facet: contracts,
+ * registries and the Chord primitives they are built from. Browser-only surface (the
+ * `Panels` registry and the React hooks) lives in `@moonan_ai/sdk/web`, because it needs
+ * React and the root entry must stay importable from a Node facet.
+ */
+export {
+	Manifest,
+	FacetSetSchema,
+	WebFacetSchema,
+	type FacetSetEntry,
+	type WebFacet,
+} from "./manifest.js";
+export { Routes, type RouteHandler } from "./routes.js";
+
+/** Chord primitives, re-exported so a plugin needs two dependencies instead of three. */
+export {
+	ChordError,
+	defineFacet,
+	defineRegistry,
+	forbidden,
+	hostFamily,
+	hostNamed,
+	invalid,
+	isChordError,
+	local,
+	method,
+	opaque,
+	remote,
+	type AnyContract,
+	type Ctx,
+	type Facet,
+	type FacetApi,
+	type Host,
+	type InputOf,
+	type JsonValue,
+	type LocalContract,
+	type Readable,
+	type Ref,
+	type RefStatus,
+	type Registry,
+	type RegistryTable,
+	type RegistryView,
+	type RemoteContract,
+	type Shape,
+} from "@earendil-works/chord";
+
+/** Explicit cancellation/context helpers; browser-safe, same entry points as chord. */
+export {
+	BACKGROUND_CONTEXT,
+	awaitWithContext,
+	traceIn,
+	withAbortSignal,
+	withCancel,
+	withoutAbortSignal,
+	type Context,
+} from "@earendil-works/chord/context";
+
+/** The schema builder every contract is written with. */
+export { Type, type Static, type TSchema } from "typebox";

package/src/manifest.ts

@@ -0,0 +1,70 @@
+import { hostNamed, remote } from "@earendil-works/chord";
+import { Type, type Static } from "typebox";
+
+/**
+ * A browser facet: the module URL and a hash of its exact file contents.
+ *
+ * The URL alone cannot tell a client that the file changed; a server reload with the same
+ * path would otherwise look identical. The hash is what makes a browser reload only when
+ * its web code actually changed.
+ */
+export const WebFacetSchema = Type.Object({
+	/** Absolute path on this server (`/facets/<key>/web.js`). */
+	url: Type.String(),
+	/** SHA-256 of the file contents, truncated for display. */
+	hash: Type.String(),
+});
+export type WebFacet = Static<typeof WebFacetSchema>;
+
+/**
+ * One plugin's facets, as the browser needs to know them.
+ *
+ * `name` is a display label derived from the directory or package; it is not an identity.
+ * The runtime identity of a facet is its module URL. A server-only plugin has no `web`, and
+ * a plugin that failed to resolve carries `error` instead — the browser still receives it,
+ * so the shell can report the failure rather than show a silently missing tab.
+ */
+export const FacetSetSchema = Type.Object({
+	name: Type.String(),
+	version: Type.String(),
+	/** Where the facets came from: an installed package, or a directory on disk. */
+	source: Type.Union([Type.Literal("package"), Type.Literal("directory")]),
+	web: Type.Optional(WebFacetSchema),
+	error: Type.Optional(Type.String()),
+});
+export type FacetSetEntry = Static<typeof FacetSetSchema>;
+
+/**
+ * The only object the platform publishes: which browser facets the browser host must load.
+ *
+ * This is the seam that keeps the platform free of feature state. The loader knows which
+ * modules exist; the browser cannot find that out alone (it has no filesystem and no
+ * registry to ask), so exactly one read-only object carries it across. Chord names a
+ * server `Manifest` object as how browsers learn of changes (spec §6); the particular
+ * fields here are Moonan application state, not protocol fields.
+ *
+ * Contract version 3 changed `web` from a bare URL string to `{ url, hash }`. There is no
+ * compatibility adapter: a browser is mapped to `upgrade_required` and must load the new
+ * shell (a non-client consumer gets `contract_mismatch`).
+ */
+export const Manifest = remote("moonan.manifest", {
+	version: 3,
+	input: Type.Object({}),
+	host: hostNamed("moonan"),
+	variants: {
+		v1: {
+			state: {
+				/** The platform's own version, so a client can tell which build it is talking to. */
+				version: Type.String(),
+				facets: Type.Array(FacetSetSchema),
+				/**
+				 * chord's code version (`host.codeVersion`): 1 at startup, one higher after every
+				 * reload that committed. This is Moonan application state, not chord's removed
+				 * `Shape.codeVersion`; a browser decides whether to reload from each `web.hash`,
+				 * and never from this number as a protocol value.
+				 */
+				revision: Type.Number(),
+			},
+		},
+	},
+});

package/src/routes.ts

@@ -0,0 +1,23 @@
+import { defineRegistry } from "@earendil-works/chord";
+import type { Ctx } from "@earendil-works/chord";
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+/**
+ * One HTTP handler a plugin contributes.
+ *
+ * `ctx` is the root the platform opened for this request: a handler that calls into an
+ * object passes it along, so the call belongs to the request and ends with it. Handlers
+ * are short — a response that needs to outlive the request (a stream, a long poll) is
+ * the wrong shape here, and should hold its state in a cell and answer in another call.
+ */
+export type RouteHandler = (request: IncomingMessage, response: ServerResponse, ctx: Ctx) => void | Promise<void>;
+
+/**
+ * The server-side way out of the object protocol.
+ *
+ * Chord covers everything object-to-object; it has no opinion about plain HTTP, and the
+ * platform serves exactly one port for both. This registry is the hook between them:
+ * the keys are `"GET /path"` for one method, or `"/path"` for any. A request that matches
+ * nothing falls through to the built-in endpoints, the facet assets and the shell.
+ */
+export const Routes = defineRegistry<RouteHandler>("moonan.routes", { conflict: "error" });

package/src/web.ts

@@ -0,0 +1,230 @@
+import {
+	defineRegistry,
+	isChordError,
+	type AnyContract,
+	type Host,
+	type InputOf,
+	type Readable,
+	type Ref,
+	type RefStatus,
+} from "@earendil-works/chord";
+import { useEffect, useLayoutEffect, useRef, useState, type ReactNode } from "react";
+
+export type { InputOf, Readable, Ref, RefStatus } from "@earendil-works/chord";
+export { isChordError } from "@earendil-works/chord";
+
+/**
+ * A `gone` error that no new reference can fix: the consumer was built against a contract the
+ * provider no longer covers. For the shell's own contracts (the platform `Manifest`, or a
+ * protocol mismatch) the page needs the new build. For a plugin's contract, chord's remedy is
+ * to reload the web facets; the shell does that when the manifest reports changed facets.
+ */
+export function isFatalContractError(error: unknown): boolean {
+	return isChordError(error, "contract_mismatch") || isChordError(error, "upgrade_required");
+}
+
+/** Options of {@link useRemote}. */
+export interface UseRemoteOptions {
+	/**
+	 * Called once when the reference can no longer be recovered: a non-retryable contract
+	 * error, or a `gone` reference after the bounded retries. The shell uses this to reload
+	 * the page instead of rendering a permanently loading screen.
+	 */
+	onFatal?: (error: unknown) => void;
+}
+
+/**
+ * What the shell hands to a panel: the browser chord host, and nothing else.
+ *
+ * Every reference a panel holds comes from here — `useRemote(host, …)`. The shell owns
+ * no application state to pass down, which is what keeps it from acquiring opinions.
+ */
+export interface PanelProps {
+	host: Host<unknown>;
+}
+
+/** One top-level page a browser facet contributes. */
+export interface PanelContribution {
+	id: string;
+	/** The tab label. Data, not a shell dictionary key: the shell has no dictionary. */
+	title: string;
+	/** Ascending; ties keep registration order. */
+	order?: number;
+	component: (props: PanelProps) => ReactNode;
+}
+
+/**
+ * The browser-side way into the shell's navigation.
+ *
+ * Chord registries are per host, and a panel component cannot cross the wire, so the
+ * registry lives in the browser host and is filled by the plugin's own browser facet.
+ * The shell subscribes and renders; it never imports a panel.
+ */
+export const Panels = defineRegistry<PanelContribution>("moonan.panels", { conflict: "error" });
+
+/**
+ * Reads a state member, falling back while it has no value yet.
+ *
+ * `hold` returns before the object is live, and chord reports that as `not_ready` when the
+ * member is read — a transition, not a failure. `not_in_variant` is the other expected one:
+ * the provider's variant does not carry this member. Anything else is a bug in the read
+ * path and is reported rather than hidden behind the fallback.
+ */
+function readOr<T>(readable: Readable<T> | undefined, fallback: T): T {
+	if (!readable) return fallback;
+	try {
+		return readable.value;
+	} catch (error) {
+		if (isChordError(error, "not_ready") || isChordError(error, "not_in_variant")) return fallback;
+		console.error("[chord] reading state failed", error);
+		return fallback;
+	}
+}
+
+/**
+ * Acquires a reference from the browser host with `host.hold`.
+ *
+ * `hold` is the API chord designates for UI runtimes: synchronous, possibly still
+ * `loading`, and re-held by the runtime itself when the link comes back, so a reconnect
+ * costs no new reference. It is acquired in a layout effect rather than during render:
+ * that keeps the impossible-to-render intermediate commit off the screen, and makes the
+ * acquire/release pair symmetrical under StrictMode's mount → unmount → mount (a
+ * reference taken during render would leak the discarded one).
+ */
+export function useRemote<C extends AnyContract>(
+	host: Host<unknown> | null | undefined,
+	contract: C,
+	input: InputOf<C>,
+	options: UseRemoteOptions = {},
+): Ref<C> | null {
+	// The input is a plain JSON address, and a panel commonly passes a fresh `{}` each
+	// render. Key on its content so identity churn does not re-acquire the reference.
+	const key = JSON.stringify(input);
+	const [ref, setRef] = useState<Ref<C> | null>(null);
+	const [attempt, setAttempt] = useState(0);
+	const retries = useRef(0);
+	const fatalReported = useRef(false);
+	const warned = useRef(false);
+	const onFatal = useRef(options.onFatal);
+	onFatal.current = options.onFatal;
+
+	useLayoutEffect(() => {
+		if (!host) {
+			setRef(null);
+			return;
+		}
+		let held: Ref<C>;
+		try {
+			held = host.hold(contract, JSON.parse(key) as InputOf<C>);
+		} catch (error) {
+			// A type this host cannot place (an unknown name, a local type it does not serve).
+			console.error("[chord] hold failed", error);
+			setRef(null);
+			return;
+		}
+		setRef(held);
+		return () => {
+			setRef(null);
+			held.release();
+		};
+	}, [host, contract, key, attempt]);
+
+	useEffect(() => {
+		if (!ref) return;
+		return ref.onStatus((status: RefStatus, error: unknown) => {
+			// A reconnect re-holds in place (`loading`, last values readable) and needs nothing.
+			// `gone` is terminal for this reference — the object was forced away while held —
+			// and chord's guidance for a UI is to take a new one. Bounded, so a provider that
+			// keeps answering `gone` cannot spin the page.
+			if (status === "live") {
+				retries.current = 0;
+				fatalReported.current = false;
+				warned.current = false;
+				return;
+			}
+			if (status !== "gone") return;
+
+			// A contract that the provider no longer covers cannot be fixed by taking another
+			// reference. The shell owns the official remedy (reload the web facets when the
+			// manifest reports changed facets); a panel only reports it upward, and without an
+			// `onFatal` handler it says once what the developer can do.
+			if (isFatalContractError(error)) {
+				const handler = onFatal.current;
+				if (handler !== undefined) {
+					if (!fatalReported.current) {
+						fatalReported.current = true;
+						handler(error);
+					}
+					return;
+				}
+				if (!warned.current) {
+					warned.current = true;
+					console.warn(
+						"[chord] a reference is gone because its contract no longer binds. The shell reloads web facets when the Manifest reports changed facets; if this persists, the plugin's web code and contract are out of sync.",
+						error,
+					);
+				}
+				return;
+			}
+
+			if (retries.current < 3) {
+				retries.current += 1;
+				setAttempt((value) => value + 1);
+				return;
+			}
+			if (!fatalReported.current) {
+				fatalReported.current = true;
+				onFatal.current?.(error);
+			}
+		});
+	}, [ref]);
+
+	return ref;
+}
+
+/**
+ * Follows a reference's status: `loading | live | released | gone`.
+ *
+ * `hold` returns before the object is live, so a panel renders from this instead of
+ * guessing. `gone` is the state that needs a new reference — a forced disposal, a host
+ * that closed, a contract the provider no longer serves.
+ */
+export function useRefStatus<C extends AnyContract>(ref: Ref<C> | null): RefStatus | null {
+	const [status, setStatus] = useState<RefStatus | null>(() => ref?.status ?? null);
+
+	// Layout effect: the reference is acquired in one, and this is what turns that commit
+	// into a painted one. With a passive effect the first paint would still say "loading".
+	useLayoutEffect(() => {
+		if (!ref) {
+			setStatus(null);
+			return;
+		}
+		setStatus(ref.status);
+		return ref.onStatus((next: RefStatus) => setStatus(next));
+	}, [ref]);
+
+	return status;
+}
+
+/** Renders the current value of a chord `Readable`, and every later one. */
+export function useReadable<T>(readable: Readable<T> | undefined, fallback: T): T {
+	const [value, setValue] = useState<T>(() => readOr(readable, fallback));
+
+	useLayoutEffect(() => {
+		if (!readable) {
+			setValue(fallback);
+			return;
+		}
+		let cancelled = false;
+		setValue(readOr(readable, fallback));
+		const stop = readable.subscribe((next: T) => {
+			if (!cancelled) setValue(next);
+		});
+		return () => {
+			cancelled = true;
+			stop();
+		};
+	}, [readable]);
+
+	return value;
+}