@moonan_ai/sdk 0.0.0-stage → 0.0.5-alpha1

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,82 @@
-# 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`、`DataCodecs`、`ModelProviders`）必须来自 `{ lifetime: "host" }` 的对象。
+- 需要统一导出/导入的数据放 `DataStore`，并注册 `DataCodecs`；需要给其他插件用模型时注册 `ModelProviders`。
+- 服务端宿主名固定为 `"moonan"`；写别的名字，`api.serve` 会当场拒绝。
+- 浏览器切面是**单个 ESM 文件**：浏览器没有模块 hook，重载只换入口。
+
+## 统一数据与模型
+
+```js
+import { DataCodecs, DataStore, ModelProviders } from "@moonan_ai/sdk";
+```
+
+- `DataStore` 是平台唯一的统一数据文件（local、host-lifetime）；`read` 返回 `{ value, version }`，`update` 是串行读改写，`exportAll`/`importAll` 由平台 HTTP 表面调用。
+- `DataCodecs` 是插件贡献的导出/导入 codec 注册表；没有 codec 的 namespace 不会进入统一导出。
+- `ModelProviders` 是服务端模型提供商注册表；`list()` 是 key-free 目录，`runtime()` 是 server-only 运行时，不能给浏览器。
+
+完整写法：<https://github.com/Pheobe-Southwood/Moonan/blob/main/docs/plugins.md> ·
+词汇表：<https://github.com/Pheobe-Southwood/Moonan/blob/main/CONTEXT.md>
+
+## 许可
+
+MIT

package/dist/data.js

@@ -0,0 +1,90 @@
+import { defineRegistry, local, method } from "@earendil-works/chord";
+import { Type } from "typebox";
+/**
+ * One value in the platform's unified data store.
+ *
+ * `version` belongs to the dataset, not to the file and not to the contract. A plugin
+ * raises it when the stored shape or meaning changes and supplies a migration through its
+ * {@link DatasetCodec}; the platform never interprets the value.
+ */
+export const StoredDatasetSchema = Type.Object({
+    value: Type.Any(),
+    version: Type.Number(),
+}, { additionalProperties: false });
+/** Identity helper; keeps the codec's type while documenting intent. */
+export function defineDataset(codec) {
+    return codec;
+}
+/**
+ * The registry of dataset codecs.
+ *
+ * A contribution must come from an object of `lifetime: "host"`, like every other Chord
+ * registry. The platform reads the table for the code version of the root that asks.
+ */
+export const DataCodecs = defineRegistry("moonan.data-codecs", {
+    conflict: "error",
+});
+/**
+ * What the data store reports about its file. This is a state member, so a plugin can read
+ * it synchronously once the store is live; the platform also exposes it over HTTP.
+ */
+export const DataStoreStorageInfoSchema = Type.Object({
+    file: Type.String(),
+    backup: Type.String(),
+    exists: Type.Boolean(),
+    mode: Type.Optional(Type.String()),
+    writable: Type.Boolean(),
+    revision: Type.Number(),
+    datasets: Type.Number(),
+    lastSavedAt: Type.Optional(Type.String()),
+    notice: Type.Optional(Type.String()),
+}, { additionalProperties: false });
+/**
+ * The wire/JSON envelope for a complete export. The file itself has a different, richer
+ * shape (it also keeps per-dataset timestamps); this is the portable subset.
+ */
+export const DataBundleSchema = Type.Object({
+    format: Type.Literal("moonan.data"),
+    formatVersion: Type.Literal(1),
+    createdAt: Type.String(),
+    revision: Type.Number(),
+    datasets: Type.Array(Type.Object({
+        namespace: Type.String(),
+        version: Type.Number(),
+        value: Type.Any(),
+    }, { additionalProperties: false })),
+    skipped: Type.Optional(Type.Array(Type.String())),
+}, { additionalProperties: false });
+export const DataImportReportSchema = Type.Object({
+    imported: Type.Array(Type.String()),
+    revision: Type.Number(),
+    skipped: Type.Optional(Type.Array(Type.String())),
+}, { additionalProperties: false });
+/**
+ * The platform's unified data service.
+ *
+ * It is local and host-lifetime: exactly one object exists for the server host, it owns
+ * the only data file, and every plugin reads/writes through it. It is not a remote type;
+ * browsers get data through plugin methods or the platform's export/import HTTP surface.
+ *
+ * `read` returns the raw `{ value, version }` and deliberately does not consult a codec:
+ * a plugin's `config` cell may initialize before its codec registration is published, so
+ * the plugin validates/migrates its own first value. `write` replaces a whole dataset;
+ * `update` is the read-modify-write form that runs inside the store's serial queue.
+ */
+export const DataStore = local("moonan.data", {
+    version: 1,
+    input: Type.Object({}),
+    members: {
+        revision: Type.Number(),
+        storage: DataStoreStorageInfoSchema,
+        read: method(Type.Object({ namespace: Type.String() }), Type.Any()),
+        write: method(Type.Object({ namespace: Type.String(), version: Type.Number(), value: Type.Any() }), StoredDatasetSchema),
+        update: method(Type.Object({ namespace: Type.String(), version: Type.Number(), update: Type.Any() }), StoredDatasetSchema),
+        remove: method(Type.Object({ namespace: Type.String() })),
+        reload: method(undefined, DataStoreStorageInfoSchema),
+        exportAll: method(Type.Object({ includeSecrets: Type.Optional(Type.Boolean()) }), DataBundleSchema),
+        importAll: method(Type.Object({ bundle: DataBundleSchema }), DataImportReportSchema),
+    },
+});
+//# sourceMappingURL=data.js.map

package/dist/data.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data.js","sourceRoot":"","sources":["../src/data.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,EAAkB,MAAM,uBAAuB,CAAC;AACtF,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAE/B;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,IAAI,CAAC,MAAM,CAC7C;IACC,KAAK,EAAE,IAAI,CAAC,GAAG,EAAE;IACjB,OAAO,EAAE,IAAI,CAAC,MAAM,EAAE;CACtB,EACD,EAAE,oBAAoB,EAAE,KAAK,EAAE,CAC/B,CAAC;AAqCF,wEAAwE;AACxE,MAAM,UAAU,aAAa,CAAI,KAAsB;IACtD,OAAO,KAAK,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,cAAc,CAAe,oBAAoB,EAAE;IAC5E,QAAQ,EAAE,OAAO;CACjB,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,IAAI,CAAC,MAAM,CACpD;IACC,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE;IACnB,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE;IACrB,MAAM,EAAE,IAAI,CAAC,OAAO,EAAE;IACtB,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;IAClC,QAAQ,EAAE,IAAI,CAAC,OAAO,EAAE;IACxB,QAAQ,EAAE,IAAI,CAAC,MAAM,EAAE;IACvB,QAAQ,EAAE,IAAI,CAAC,MAAM,EAAE;IACvB,WAAW,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;IACzC,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;CACpC,EACD,EAAE,oBAAoB,EAAE,KAAK,EAAE,CAC/B,CAAC;AAcF;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAC,MAAM,CAC1C;IACC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC;IACnC,aAAa,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;IAC9B,SAAS,EAAE,IAAI,CAAC,MAAM,EAAE;IACxB,QAAQ,EAAE,IAAI,CAAC,MAAM,EAAE;IACvB,QAAQ,EAAE,IAAI,CAAC,KAAK,CACnB,IAAI,CAAC,MAAM,CACV;QACC,SAAS,EAAE,IAAI,CAAC,MAAM,EAAE;QACxB,OAAO,EAAE,IAAI,CAAC,MAAM,EAAE;QACtB,KAAK,EAAE,IAAI,CAAC,GAAG,EAAE;KACjB,EACD,EAAE,oBAAoB,EAAE,KAAK,EAAE,CAC/B,CACD;IACD,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;CACjD,EACD,EAAE,oBAAoB,EAAE,KAAK,EAAE,CAC/B,CAAC;AAWF,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAI,CAAC,MAAM,CAChD;IACC,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;IACnC,QAAQ,EAAE,IAAI,CAAC,MAAM,EAAE;IACvB,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;CACjD,EACD,EAAE,oBAAoB,EAAE,KAAK,EAAE,CAC/B,CAAC;AAQF;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,KAAK,CAAC,aAAa,EAAE;IAC7C,OAAO,EAAE,CAAC;IACV,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;IACtB,OAAO,EAAE;QACR,QAAQ,EAAE,IAAI,CAAC,MAAM,EAAE;QACvB,OAAO,EAAE,0BAA0B;QACnC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC;QACnE,KAAK,EAAE,MAAM,CACZ,IAAI,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,EACpF,mBAAmB,CACnB;QACD,MAAM,EAAE,MAAM,CACb,IAAI,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,EACrF,mBAAmB,CACnB;QACD,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACzD,MAAM,EAAE,MAAM,CAAC,SAAS,EAAE,0BAA0B,CAAC;QACrD,SAAS,EAAE,MAAM,CAChB,IAAI,CAAC,MAAM,CAAC,EAAE,cAAc,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,EAC9D,gBAAgB,CAChB;QACD,SAAS,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC,EAAE,sBAAsB,CAAC;KACpF;CACD,CAAC,CAAC"}

package/dist/index.js

@@ -0,0 +1,20 @@
+/**
+ * `@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 (including `DataCodecs` and `ModelProviders`) 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 { WebFacetCatalog, FacetSetSchema, WebFacetSchema, } from "./web-facet-catalog.js";
+export { DataStore, DataCodecs, DataBundleSchema, DataImportReportSchema, DataStoreStorageInfoSchema, StoredDatasetSchema, defineDataset, } from "./data.js";
+export { ModelProviders, } from "./model-provider.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;;;;;;;;GAQG;AACH,OAAO,EACN,eAAe,EACf,cAAc,EACd,cAAc,GAGd,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACN,SAAS,EACT,UAAU,EACV,gBAAgB,EAChB,sBAAsB,EACtB,0BAA0B,EAC1B,mBAAmB,EACnB,aAAa,GAOb,MAAM,WAAW,CAAC;AACnB,OAAO,EACN,cAAc,GAGd,MAAM,qBAAqB,CAAC;AAC7B,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/model-provider.js

@@ -0,0 +1,5 @@
+import { defineRegistry } from "@earendil-works/chord";
+export const ModelProviders = defineRegistry("moonan.model-providers", {
+    conflict: "error",
+});
+//# sourceMappingURL=model-provider.js.map

package/dist/model-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-provider.js","sourceRoot":"","sources":["../src/model-provider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AA0CvD,MAAM,CAAC,MAAM,cAAc,GAAG,cAAc,CAAgB,wBAAwB,EAAE;IACrF,QAAQ,EAAE,OAAO;CACjB,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-facet-catalog.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: the catalog of 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.
+ *
+ * The name is deliberately about what it carries: a catalog of web facets. It is not a
+ * package manifest and it is not a general application manifest. This is a fresh contract
+ * (version 1) with no compatibility adapter: an old shell gets `upgrade_required` and
+ * reloads the page.
+ */
+export const WebFacetCatalog = remote("moonan.web-facets", {
+    version: 1,
+    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=web-facet-catalog.js.map

package/dist/web-facet-catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-facet-catalog.js","sourceRoot":"","sources":["../src/web-facet-catalog.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,eAAe,GAAG,MAAM,CAAC,mBAAmB,EAAE;IAC1D,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/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 `WebFacetCatalog`, 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 WebFacetCatalog 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
+            // WebFacetCatalog 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 WebFacetCatalog 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.5-alpha1",
+  "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/data.ts

@@ -0,0 +1,184 @@
+import { defineRegistry, local, method, type JsonValue } from "@earendil-works/chord";
+import { Type } from "typebox";
+
+/**
+ * One value in the platform's unified data store.
+ *
+ * `version` belongs to the dataset, not to the file and not to the contract. A plugin
+ * raises it when the stored shape or meaning changes and supplies a migration through its
+ * {@link DatasetCodec}; the platform never interprets the value.
+ */
+export const StoredDatasetSchema = Type.Object(
+	{
+		value: Type.Any(),
+		version: Type.Number(),
+	},
+	{ additionalProperties: false },
+);
+
+export type StoredDataset = {
+	value: JsonValue;
+	version: number;
+};
+
+/**
+ * What every plugin must contribute to make its dataset exportable and importable.
+ *
+ * The codec is a registry value, not a Chord contract: it lives in the server host, can
+ * carry functions, and never crosses a link. The platform calls it when an administrator
+ * exports or imports the unified data file.
+ */
+export interface DatasetCodec<T = unknown> {
+	/** Stable dataset key, conventionally `"<package>/<dataset>"`. */
+	readonly namespace: string;
+	/** Current stored shape version; see {@link StoredDataset.version}. */
+	readonly version: number;
+	/** Convert an older stored value to the current stored value. */
+	migrate(value: JsonValue, fromVersion: number): T;
+	/** Convert the current stored value to a portable export value (redact secrets here). */
+	export(value: T, options: DatasetExportOptions): JsonValue;
+	/**
+	 * Convert an imported export value to the current stored value.
+	 *
+	 * `current` is the value already stored at this namespace, if any. A codec may use it
+	 * to preserve secrets that a redacted export deliberately omitted.
+	 */
+	import(value: JsonValue, fromVersion: number, current: JsonValue | undefined): T;
+}
+
+export interface DatasetExportOptions {
+	/** False by default on the HTTP surface; a codec must redact secrets when false. */
+	readonly includeSecrets: boolean;
+}
+
+/** Identity helper; keeps the codec's type while documenting intent. */
+export function defineDataset<T>(codec: DatasetCodec<T>): DatasetCodec<T> {
+	return codec;
+}
+
+/**
+ * The registry of dataset codecs.
+ *
+ * A contribution must come from an object of `lifetime: "host"`, like every other Chord
+ * registry. The platform reads the table for the code version of the root that asks.
+ */
+export const DataCodecs = defineRegistry<DatasetCodec>("moonan.data-codecs", {
+	conflict: "error",
+});
+
+/**
+ * What the data store reports about its file. This is a state member, so a plugin can read
+ * it synchronously once the store is live; the platform also exposes it over HTTP.
+ */
+export const DataStoreStorageInfoSchema = Type.Object(
+	{
+		file: Type.String(),
+		backup: Type.String(),
+		exists: Type.Boolean(),
+		mode: Type.Optional(Type.String()),
+		writable: Type.Boolean(),
+		revision: Type.Number(),
+		datasets: Type.Number(),
+		lastSavedAt: Type.Optional(Type.String()),
+		notice: Type.Optional(Type.String()),
+	},
+	{ additionalProperties: false },
+);
+
+export type DataStoreStorageInfo = {
+	file: string;
+	backup: string;
+	exists: boolean;
+	mode?: string;
+	writable: boolean;
+	revision: number;
+	datasets: number;
+	lastSavedAt?: string;
+	notice?: string;
+};
+
+/**
+ * The wire/JSON envelope for a complete export. The file itself has a different, richer
+ * shape (it also keeps per-dataset timestamps); this is the portable subset.
+ */
+export const DataBundleSchema = Type.Object(
+	{
+		format: Type.Literal("moonan.data"),
+		formatVersion: Type.Literal(1),
+		createdAt: Type.String(),
+		revision: Type.Number(),
+		datasets: Type.Array(
+			Type.Object(
+				{
+					namespace: Type.String(),
+					version: Type.Number(),
+					value: Type.Any(),
+				},
+				{ additionalProperties: false },
+			),
+		),
+		skipped: Type.Optional(Type.Array(Type.String())),
+	},
+	{ additionalProperties: false },
+);
+
+export type DataBundle = {
+	format: "moonan.data";
+	formatVersion: 1;
+	createdAt: string;
+	revision: number;
+	datasets: { namespace: string; version: number; value: JsonValue }[];
+	skipped?: string[];
+};
+
+export const DataImportReportSchema = Type.Object(
+	{
+		imported: Type.Array(Type.String()),
+		revision: Type.Number(),
+		skipped: Type.Optional(Type.Array(Type.String())),
+	},
+	{ additionalProperties: false },
+);
+
+export type DataImportReport = {
+	imported: string[];
+	revision: number;
+	skipped?: string[];
+};
+
+/**
+ * The platform's unified data service.
+ *
+ * It is local and host-lifetime: exactly one object exists for the server host, it owns
+ * the only data file, and every plugin reads/writes through it. It is not a remote type;
+ * browsers get data through plugin methods or the platform's export/import HTTP surface.
+ *
+ * `read` returns the raw `{ value, version }` and deliberately does not consult a codec:
+ * a plugin's `config` cell may initialize before its codec registration is published, so
+ * the plugin validates/migrates its own first value. `write` replaces a whole dataset;
+ * `update` is the read-modify-write form that runs inside the store's serial queue.
+ */
+export const DataStore = local("moonan.data", {
+	version: 1,
+	input: Type.Object({}),
+	members: {
+		revision: Type.Number(),
+		storage: DataStoreStorageInfoSchema,
+		read: method(Type.Object({ namespace: Type.String() }), Type.Any()),
+		write: method(
+			Type.Object({ namespace: Type.String(), version: Type.Number(), value: Type.Any() }),
+			StoredDatasetSchema,
+		),
+		update: method(
+			Type.Object({ namespace: Type.String(), version: Type.Number(), update: Type.Any() }),
+			StoredDatasetSchema,
+		),
+		remove: method(Type.Object({ namespace: Type.String() })),
+		reload: method(undefined, DataStoreStorageInfoSchema),
+		exportAll: method(
+			Type.Object({ includeSecrets: Type.Optional(Type.Boolean()) }),
+			DataBundleSchema,
+		),
+		importAll: method(Type.Object({ bundle: DataBundleSchema }), DataImportReportSchema),
+	},
+});

package/src/index.ts

@@ -0,0 +1,83 @@
+/**
+ * `@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 (including `DataCodecs` and `ModelProviders`) 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 {
+	WebFacetCatalog,
+	FacetSetSchema,
+	WebFacetSchema,
+	type FacetSetEntry,
+	type WebFacet,
+} from "./web-facet-catalog.js";
+export {
+	DataStore,
+	DataCodecs,
+	DataBundleSchema,
+	DataImportReportSchema,
+	DataStoreStorageInfoSchema,
+	StoredDatasetSchema,
+	defineDataset,
+	type DataBundle,
+	type DataImportReport,
+	type DataStoreStorageInfo,
+	type DatasetCodec,
+	type DatasetExportOptions,
+	type StoredDataset,
+} from "./data.js";
+export {
+	ModelProviders,
+	type ModelInfo,
+	type ModelProvider,
+} from "./model-provider.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/model-provider.ts

@@ -0,0 +1,45 @@
+import { defineRegistry } from "@earendil-works/chord";
+
+/**
+ * Provider-neutral metadata for one configured chat model.
+ *
+ * This is plain JSON: the registry value never crosses a link, but keeping the catalog
+ * serializable lets a plugin expose it over HTTP or in a panel without a second shape.
+ */
+export interface ModelInfo {
+	readonly providerId: string;
+	readonly modelId: string;
+	readonly name: string;
+	readonly contextWindow?: number;
+	readonly maxTokens?: number;
+	readonly input: readonly ("text" | "image")[];
+	readonly reasoning: boolean;
+}
+
+/**
+ * A model provider contribution.
+ *
+ * `list()` is the key-free catalog. `runtime()` is a server-only handle whose concrete
+ * shape belongs to the provider package; ai-gateway returns its pi-ai `MutableModels`
+ * there. The SDK stays free of pi-ai so a generic plugin does not inherit an AI dependency.
+ *
+ * A consumer looks the provider up with the code version of its root:
+ *
+ * ```ts
+ * const providers = api.registry(ModelProviders);
+ * const provider = providers.get("ai-gateway", ctx);
+ * ```
+ *
+ * The registry value is not a Chord contract: there is no `uses` entry and no wire
+ * compatibility rule. Its table is replaced with each code version like every registry.
+ */
+export interface ModelProvider {
+	readonly id: string;
+	readonly title: string;
+	list(): readonly ModelInfo[];
+	runtime(): unknown;
+}
+
+export const ModelProviders = defineRegistry<ModelProvider>("moonan.model-providers", {
+	conflict: "error",
+});

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-facet-catalog.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: the catalog of 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.
+ *
+ * The name is deliberately about what it carries: a catalog of web facets. It is not a
+ * package manifest and it is not a general application manifest. This is a fresh contract
+ * (version 1) with no compatibility adapter: an old shell gets `upgrade_required` and
+ * reloads the page.
+ */
+export const WebFacetCatalog = remote("moonan.web-facets", {
+	version: 1,
+	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/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 `WebFacetCatalog`, 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 WebFacetCatalog 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
+			// WebFacetCatalog 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 WebFacetCatalog 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;
+}