@mawaru/sdk 0.40.0 → 0.41.0

package/dist/views/human.d.ts

@@ -1,73 +1,54 @@
 import type { ReactNode } from "react";
 import type { JsonSchema } from "../_schemas/node.js";
-/** 承認画面の局面：承認待ち／承認済み／差し戻し後（AI 再実行待ち）／失敗／キャンセル */
-export type ApprovalPhase = "waiting" | "approved" | "rejected" | "failed" | "cancelled";
-/**
- * 承認バーの材料。部品の `ApprovalBar` はこれをそのまま使う。承認バーを自分で書くときに読む。
- */
-export type ApprovalDecisionContext = {
-    /** 見ている人が今決定できる（担当で承認待ち）。全員の承認が要るノードでも true（値を直せるかは `editable`） */
-    canDecide: boolean;
-    /** 承認したあとに流れる先のノード名（つながっていなければ null） */
-    approveTargetName: string | null;
-    /** 差し戻し先のノード名（無ければ差し戻せない） */
-    rejectTargetName: string | null;
-    /** 承認・差し戻し以外の出口。`needsInput` は、今の値の型が出口と合わず、値を入れるダイアログが要るもの */
-    exits: {
-        key: string;
-        name: string;
-        needsInput: boolean;
-    }[];
-    /** 担当でない人が開いたときの、担当の名前（担当なら null） */
-    otherAssignees: string[] | null;
-    /** 全員の承認が要るときの進み具合（`approvedByMe` は自分がもう承認したか）。要らなければ null */
-    progress: {
-        done: number;
-        total: number;
-        approvedByMe: boolean;
-    } | null;
-    /** 失敗した step の理由（失敗していなければ null） */
-    failedReason: string | null;
-};
-/** mawaru から承認ビューへ渡す材料 */
-export type ApprovalViewContext<TIn = unknown> = {
-    /** 届いた値（step の input そのもの）。ビューで直した値はビューの state に持つ */
-    output: TIn;
-    /** `output` の型＝ human の in ポートの型（ビューの宣言が写っている）。`SchemaForm` に渡すとフォームになる */
-    outputSchema: JsonSchema | null;
-    /** ループ変数（この step が始まった時点の写し）。予約キー `input` が run の起動入力 */
-    refs: unknown;
-    /** この human ノードの名前 */
-    nodeName: string;
-    /** 局面 */
-    phase: ApprovalPhase;
-    /** 値を直してよい（承認待ちで、見ている人が担当。全員の承認が要るノードでは false） */
-    editable: boolean;
-    /** 承認バーの材料 */
-    decision: ApprovalDecisionContext;
+import type { FileRef } from "./_parts/fileRef.js";
+export type HumanProps<TInput = unknown, TOutput = Record<string, unknown>, TRefs = Record<string, unknown>> = {
+    /** 届いた値（in ポートの値＝ step の input） */
+    input: TInput;
+    /**
+     * 人の操作を mawaru に渡す。`{ <出口ポートのkey>: <データ> }`（program の run の戻り値と同じ1キーのオブジェクト）。
+     * 人がボタンを押した直後の呼び出しだけを受け付ける（開いただけで決定する画面は書けない）。
+     * 送れたら承認画面は run の画面へ戻る。断られたら（担当でない・もう決まっている など）理由つきで失敗する
+     */
+    out: (output: TOutput) => Promise<void>;
+    /** input 以外の材料（program の run の ctx と同じ位置づけ） */
+    ctx: {
+        input: {
+            /** input の型（in ポートの JSON Schema） */
+            schema: JsonSchema;
+            /** input に含まれるファイルを表示する URL を取る（sandbox の中からは mawaru のファイルを直接読めない） */
+            fetchFileUrl: (file: FileRef) => Promise<string>;
+        };
+        output: {
+            /** 出口ごとの型（out ポートの key → JSON Schema。approve・reject・追加の出口） */
+            schema: Record<string, JsonSchema>;
+            /** 出す値に入れるファイル（差し戻しの参考ファイルなど）を上げて、参照を受け取る */
+            uploadFile: (file: File) => Promise<FileRef>;
+        };
+        clipboard: {
+            /** クリップボードに書く（sandbox の中では使えない navigator.clipboard.writeText の代わり） */
+            writeText: (text: string) => Promise<void>;
+        };
+        /**
+         * ループ変数（この step が始まった時点の値。program の ctx.refs と同じ）。
+         * 予約キー `input` が run の起動入力
+         */
+        refs: TRefs;
+        step: {
+            /** 見ている人がこの step の担当か（担当でなければ out は断られる） */
+            isAssignee: boolean;
+            /**
+             * 値を直してよいか：担当で、全員承認のノードでないとき true
+             * （全員承認は全員が同じ値を承認するので、届いた値のまま決める）
+             */
+            editable: boolean;
+        };
+    };
 };
+/** mawaru が承認画面に描く、human ノードの画面（React のコンポーネント） */
+export type HumanView<TInput = unknown, TOutput = Record<string, unknown>, TRefs = Record<string, unknown>> = (props: HumanProps<TInput, TOutput, TRefs>) => ReactNode;
 /**
- * 承認ビュー：ctx を受けて承認画面（上の帯より下の全部）を描く React コンポーネント。
- * 承認バーは `<ApprovalBar ctx={ctx} />` を置く（置かなければ承認バーは出ない）。
+ * human ノードの実装を定義する：input と out を受けて描く関数を渡すと、画面を返す。
+ * React では props を受けて描く関数がそのままコンポーネントなので、型を付けて返すだけ
  */
-export type ApprovalView<TIn = unknown> = {
-    bivariance(props: {
-        ctx: ApprovalViewContext<TIn>;
-    }): ReactNode;
-}["bivariance"];
-/** 承認ビューを定義する。型を付けるためだけの関数（値はそのまま返す） */
-export declare const defineApprovalView: <TIn = unknown>(view: ApprovalView<TIn>) => ApprovalView<TIn>;
-/** 手元プレビュー（npx mawaru preview human/<dir>）のケース。nodes/human/<dir>/cases.ts の export default */
-export type ApprovalViewCase = {
-    name: string;
-    /** `ctx.output`（＝ step の input） */
-    input: unknown;
-    refs?: unknown;
-    /** 省略時は name */
-    nodeName?: string;
-    /** 省略時は承認待ち */
-    phase?: ApprovalPhase;
-};
-export { ApprovalBar } from "./_approval/ApprovalBar.js";
-export { type ApprovalActions, useApprovalActions } from "./_approvalActions.js";
-export * from "./index.js";
+export declare const defineHuman: <TInput = unknown, TOutput = Record<string, unknown>, TRefs = Record<string, unknown>>(render: (props: HumanProps<TInput, TOutput, TRefs>) => ReactNode) => HumanView<TInput, TOutput, TRefs>;
+export type { FileRef };

package/dist/views/human.js

@@ -1,6 +1,5 @@
-/** 承認ビューを定義する。型を付けるためだけの関数（値はそのまま返す） */
-export const defineApprovalView = (view) => view;
-export { ApprovalBar } from "./_approval/ApprovalBar.js";
-export { useApprovalActions } from "./_approvalActions.js";
-// 部品キット（土台）もここから import できる
-export * from "./index.js";
+/**
+ * human ノードの実装を定義する：input と out を受けて描く関数を渡すと、画面を返す。
+ * React では props を受けて描く関数がそのままコンポーネントなので、型を付けて返すだけ
+ */
+export const defineHuman = (render) => render;

package/dist/views/protocol.d.ts

@@ -1,5 +1,15 @@
+import type { JsonSchema } from "../_schemas/node.js";
 export declare const VIEW_MESSAGE_TAG = "mawaru:view";
 export type ThemeMode = "light" | "dark";
+export type HumanViewData = {
+    input: unknown;
+    inputSchema: JsonSchema;
+    outputSchema: Record<string, JsonSchema>;
+    refs: unknown;
+    isAssignee: boolean;
+    editable: boolean;
+};
+export type HumanRequestMethod = "out" | "fetchFileUrl" | "uploadFile" | "writeText";
 export type ViewToHost = {
     tag: typeof VIEW_MESSAGE_TAG;
     type: "ready";
@@ -11,13 +21,13 @@ export type ViewToHost = {
     tag: typeof VIEW_MESSAGE_TAG;
     type: "request";
     id: number;
-    method: string;
+    method: HumanRequestMethod;
     args: unknown;
 };
 export type HostToView = {
     tag: typeof VIEW_MESSAGE_TAG;
-    type: "ctx";
-    ctx: unknown;
+    type: "data";
+    data: HumanViewData;
     mode: ThemeMode;
 } | {
     tag: typeof VIEW_MESSAGE_TAG;

package/dist/views/protocol.js

@@ -1,5 +1,5 @@
-// sandbox iframe の中の実行部分（runtime.tsx）とホスト（mawaru の画面）とのメッセージの形。
+// sandbox iframe の中の実行部分（runtime.tsx）とホスト（mawaru の承認画面）とのメッセージの形。
 // **公開 API ではない**：iframe の中の実行部分とホストは同じデプロイの mawaru のコード（まとめるときに
-// その時点の版を同梱する）なので、いつ変えてもよい（docs/tasks/wip/承認ビューの顧客repo配置.md の「互換の管理」）。
+// その時点の版を同梱する）なので、いつ変えてもよい。
 // iframe に入る JS を小さく保つため、ここには型と定数だけを置く（ホストの検査は host.ts）
 export const VIEW_MESSAGE_TAG = "mawaru:view";

package/dist/views/runtime.d.ts

@@ -1,3 +1,2 @@
-import type { ApprovalView } from "./human.js";
-export declare const requestHost: <T>(method: string, args: unknown) => Promise<T>;
-export declare const runApprovalView: (View: ApprovalView) => void;
+import type { HumanView } from "./human.js";
+export declare const runHumanView: (View: HumanView) => void;

package/dist/views/runtime.js

@@ -1,8 +1,8 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Component } from "react";
 import { createRoot } from "react-dom/client";
-import { ApprovalActionsProvider, } from "./_approvalActions.js";
 import { ViewBridgeProvider } from "./_bridge.js";
+import { humanPropsOf } from "./_humanProps.js";
 import { VIEW_MESSAGE_TAG, } from "./protocol.js";
 const post = (message) => 
 // 受け手は親（ホスト）の window だけ。不透明オリジンの iframe からは親のオリジンを指定できない
@@ -10,7 +10,7 @@ window.parent.postMessage({ tag: VIEW_MESSAGE_TAG, ...message }, "*");
 const messageOf = (err) => err instanceof Error ? err.message : String(err);
 let nextRequestId = 1;
 const pending = new Map();
-const ctxListeners = new Set();
+const dataListeners = new Set();
 const onHostMessage = (event) => {
     if (event.source !== window.parent)
         return;
@@ -28,14 +28,14 @@ const onHostMessage = (event) => {
             waiting.reject(new Error(message.error));
         return;
     }
-    if (message.type === "ctx") {
+    if (message.type === "data") {
         document.documentElement.dataset.mode = message.mode;
-        for (const listener of ctxListeners)
-            listener(message.ctx, message.mode);
+        for (const listener of dataListeners)
+            listener(message.data);
     }
 };
 // ホストに頼む（返事が来るまで待つ）
-export const requestHost = (method, args) => new Promise((resolve, reject) => {
+const requestHost = (method, args) => new Promise((resolve, reject) => {
     const id = nextRequestId++;
     pending.set(id, {
         resolve: resolve,
@@ -43,12 +43,19 @@ export const requestHost = (method, args) => new Promise((resolve, reject) => {
     });
     post({ type: "request", id, method, args });
 });
-const bridge = {
-    fileUrl: (file) => requestHost("fileUrl", { file }),
+const ops = {
+    out: (output) => requestHost("out", { output }),
+    fetchFileUrl: (file) => requestHost("fetchFileUrl", { file }),
     uploadFile: (file) => requestHost("uploadFile", { file }),
-    copyText: (text) => requestHost("copyText", { text }),
+    writeText: (text) => requestHost("writeText", { text }),
+};
+// 部品（FilePreview・SchemaForm のファイル欄）が裏で使う口も、同じ頼みごとにつなぐ
+const bridge = {
+    fileUrl: ops.fetchFileUrl,
+    uploadFile: ops.uploadFile,
+    copyText: ops.writeText,
 };
-// 描画の例外をホストへ知らせる（ホストは標準ビューに差し替える）
+// 描画の例外をホストへ知らせる（ホストはエラーと理由を出す）
 class ReportErrors extends Component {
     state = { failed: false };
     static getDerivedStateFromError() {
@@ -61,9 +68,9 @@ class ReportErrors extends Component {
         return this.state.failed ? null : this.props.children;
     }
 }
-// iframe の中の共通の準備：ホストからのメッセージ・例外の報告。
-// 最初の ctx が届いたら render を呼ぶ（以降の ctx も同じ render に渡す）
-const startView = (render) => {
+// 実装はコンポーネント1つ。状態（直した値など）は実装が useState で持ち、材料が届き直しても
+// 同じコンポーネントとして描き直すので保たれる
+export const runHumanView = (View) => {
     window.addEventListener("message", onHostMessage);
     window.addEventListener("error", (event) => post({ type: "error", message: event.message }));
     window.addEventListener("unhandledrejection", (event) => post({ type: "error", message: messageOf(event.reason) }));
@@ -71,16 +78,9 @@ const startView = (render) => {
     if (!container)
         throw new Error("#root がありません");
     const root = createRoot(container);
-    ctxListeners.add((ctx) => root.render(_jsx(ViewBridgeProvider, { bridge: bridge, children: _jsx(ReportErrors, { children: render(ctx) }) })));
+    dataListeners.add((data) => {
+        const props = humanPropsOf(data, ops);
+        root.render(_jsx(ViewBridgeProvider, { bridge: bridge, children: _jsx(ReportErrors, { children: _jsx(View, { ...props }) }) }));
+    });
     post({ type: "ready" });
 };
-// ---- 承認ビュー ----
-const actions = {
-    decide: (port, value) => requestHost("decide", { port, value }),
-    openRejectDialog: () => requestHost("openRejectDialog", {}),
-    openExitDialog: (key, value) => requestHost("openExitDialog", { key, value }),
-    close: () => requestHost("close", {}),
-};
-// ビューはコンポーネント1つ。状態（直した値・選択など）はビューが useState で持ち、ctx が変わっても
-// （局面・担当の更新）同じコンポーネントとして描き直すので保たれる
-export const runApprovalView = (View) => startView((ctx) => (_jsx(ApprovalActionsProvider, { value: actions, children: _jsx(View, { ctx: ctx }) })));

package/dist/views/sample.d.ts

@@ -0,0 +1,22 @@
+type Input = {
+    subject: string;
+    body: string;
+};
+type Outputs = {
+    approve: {
+        subject: string;
+        body: string;
+    };
+    reject: {
+        prompt: string;
+    };
+};
+type Output = {
+    approve: Outputs["approve"];
+    reject?: never;
+} | {
+    reject: Outputs["reject"];
+    approve?: never;
+};
+declare const _default: import("./human.js").HumanView<Input, Output, Record<string, unknown>>;
+export default _default;

package/dist/views/sample.js

@@ -0,0 +1,38 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from "react";
+import { defineHuman } from "./human.js";
+export default defineHuman(({ input, out }) => {
+    const [reply, setReply] = useState(input);
+    const [prompt, setPrompt] = useState("");
+    return (_jsxs("div", { style: {
+            maxWidth: "720px",
+            margin: "0 auto",
+            padding: "var(--space-8) var(--space-6)",
+            display: "flex",
+            flexDirection: "column",
+            gap: "var(--space-3)",
+        }, children: [_jsx("input", { value: reply.subject, onChange: (e) => setReply({ ...reply, subject: e.target.value }), style: {
+                    padding: "var(--space-2) var(--space-3)",
+                    border: "var(--border-w) solid var(--border)",
+                    borderRadius: "var(--radius-s)",
+                    background: "var(--surface)",
+                    color: "var(--ink)",
+                    font: "inherit",
+                } }), _jsx("textarea", { value: reply.body, onChange: (e) => setReply({ ...reply, body: e.target.value }), style: {
+                    minHeight: "16em",
+                    padding: "var(--space-2) var(--space-3)",
+                    border: "var(--border-w) solid var(--border)",
+                    borderRadius: "var(--radius-s)",
+                    background: "var(--surface)",
+                    color: "var(--ink)",
+                    font: "inherit",
+                } }), _jsx("div", { style: { display: "flex", justifyContent: "flex-end" }, children: _jsx("button", { type: "button", className: "primary", disabled: reply.body.trim() === "", onClick: () => out({ approve: reply }), children: "\u3053\u306E\u5185\u5BB9\u3067\u9001\u4FE1" }) }), _jsxs("div", { style: { display: "flex", gap: "var(--space-2)" }, children: [_jsx("input", { value: prompt, placeholder: "\u5DEE\u3057\u623B\u3057\u306E\u7406\u7531", onChange: (e) => setPrompt(e.target.value), style: {
+                            flex: 1,
+                            padding: "var(--space-2) var(--space-3)",
+                            border: "var(--border-w) solid var(--border)",
+                            borderRadius: "var(--radius-s)",
+                            background: "var(--surface)",
+                            color: "var(--ink)",
+                            font: "inherit",
+                        } }), _jsx("button", { type: "button", className: "ghost", disabled: prompt.trim() === "", onClick: () => out({ reject: { prompt } }), children: "\u5DEE\u3057\u623B\u3059" })] })] }));
+});

package/docs/development.md

@@ -19,7 +19,7 @@ nodes/
   program/<dir>/   # Program ノード：config.json ＋ main.ts（＋任意で package.json）
   ai/<dir>/        # AI ノード定義：config.json
   hook/<dir>/      # NodeIOHook：config.json ＋ main.ts（ノードに付く観測フック）
-  human/<dir>/     # Human ノードの実装（承認画面）：config.json ＋ index.tsx（＋手元プレビュー用の cases.ts）
+  human/<dir>/     # Human ノードの実装（承認画面）：config.json ＋ index.tsx
 skills/<dir>/      # AI ノードが参照する skill（SKILL.md）
 views/
   slack/<name>/    # Slack ビュー：index.ts（＋手元プレビュー用の cases.ts）
@@ -102,40 +102,39 @@ views/
 
 ## Human ノード（`nodes/human/<dir>/`）
 
-- human ノードの実装＝承認画面の、上の帯より下の全部（書類と承認バー）を描く React のビュー。ノードの「承認画面」に
-  ディレクトリ名を選ぶと使われる（program / AI と同じく、ブランチ（ref）も指せる）。選ばなければ mawaru の標準の承認画面。
-  右上の閉じるボタン・差し戻しと追加の出口のダイアログ・承認の送信は mawaru が持つ
-- `config.json` — 宣言（human のポート型）。形は AI の config.json に揃える：
-  `{ "inputs": { "in": { "schema": … } }, "outputs": { "approve": …, "reject": … } }`。
-  `inputs.in` を省略すると上流の型をそのまま受ける、`outputs.approve` を省略すると in と同型、`outputs.reject` を省略すると
-  標準の差し戻し（指示＋参考ファイル）。`type` の配列（nullable）は使えない（任意の値は required から外す）。
-  エディタでディレクトリを選んだときに宣言がノードへ写る。**config.json を変えたら、エディタで選び直してから publish する**
-  （固定する commit の宣言とノードの写しが違うと publish が 422 になる。program / AI と同じ）
-- `index.tsx` — `export default defineApprovalView<In>(({ ctx }) => …)`。ビューはコンポーネント1つで、状態（直した値・選択など）は
-  `useState` で持つ。**承認バーは `<ApprovalBar ctx={ctx} label=… disabled=… output=… />` を自分で置く**（置かないと
-  承認バーは出ない）。`output` は承認で approve に流す値（省略時は `ctx.output`）。書き方の例：
-  `<div style={{ minHeight: "100%", display: "flex", flexDirection: "column" }}><div style={{ flex: 1 }}>…</div><ApprovalBar ctx={ctx} /></div>`
-  （承認バーは下に貼り付く）
-- 契約（型・ctx の中身）と部品（`ApprovalBar`・`SchemaForm`・`Markdown`・`Linkify`・`FilePreview`・`useNarrow` など）は
-  すべて `@mawaru/sdk/human` から import する。型は `npx mawaru typegen` が config.json から
-  `types.d.ts`（`In` / `Approve` / `Reject`。file は `FileRef`）を作る
+- human ノードの実装＝「input を受け取り、人の操作で出口（approve・reject・追加の出口）に値を出す」画面。
+  program の `run(input, ctx)` が `{ <出口ポートのkey>: <データ> }` を返すのと同じ形で、human はそれを人が画面で選ぶ。
+  ノードの「承認画面」にディレクトリ名を選ぶと使われる（program / AI と同じく、ブランチ（ref）も指せる）。
+  選ばなければ mawaru の標準の承認画面
+- `config.json` — 入出力スキーマの宣言。正は `_schemas/human-manifest.ts`。形は AI の config.json に揃える：
+  `{ "inputs": { "in": { "schema": … } }, "outputs": { "approve": …, "reject": …, <追加の出口>: … } }`。
+  in・approve・reject は全部書く（program と同じく必須）。program / AI と同じく、エディタでディレクトリを選ぶとこの宣言から
+  ポートができ、エディタでポートの型を直すと保存時に config.json へ書き戻される（`refs` もエディタが転写する）
+- `index.tsx` — `export default defineHuman<Input, Output, Refs>(({ input, out, ctx }) => …)`（`@mawaru/sdk/human`）。
+  React のコンポーネント1つで、状態（直した値・選択など）は `useState` で持つ
+  - `input`：届いた値（in ポートの値）
+  - `out({ <出口key>: 値 })`：人の操作を mawaru に渡す（出口は1つだけ）。人がボタンを押した直後の呼び出しだけを受け付ける
+    （開いただけで決定する画面は書けない）。送れたら承認画面は run の画面へ戻る。断られたら（担当でない・もう決まっている など）
+    Promise が理由つきで失敗する
+  - `ctx.input.schema`（in の型）・`ctx.input.fetchFileUrl(file)`（input のファイルを表示する URL）・
+    `ctx.output.schema`（出口ごとの型）・`ctx.output.uploadFile(file)`（出すファイルを上げて参照を受け取る。差し戻しの参考ファイルなど）・
+    `ctx.clipboard.writeText(text)`（コピー）・`ctx.refs`（ループ変数。`ctx.refs.input` が run の起動入力）・
+    `ctx.step.isAssignee`（見ている人が担当か）・`ctx.step.editable`（値を直してよいか。担当で、全員承認のノードでないとき true）
+  - 承認・差し戻し・追加の出口のボタンも実装が置く。差し戻しの理由や参考ファイルを入れる欄も実装が作る
+- 型は `npx mawaru typegen` が config.json から `types.d.ts`（program と同じ `Input` / `Outputs` / `Output` / `Refs`。file は `FileRef`）を作る
+- 共通の部品（`SchemaForm`・`Markdown`・`Linkify`・`FilePreview`・`useNarrow` など）は `@mawaru/sdk/components` から import する
+  （`FilePreview` と `SchemaForm` のファイル欄は、承認画面の中では自動的に mawaru に頼む口につながる）
 - エディタの型検査には repo ルートの `tsconfig.json`（`jsx: react-jsx`・`moduleResolution: Bundler`・`include: ["nodes/human", "views"]`）と
   devDependencies の `@types/react` が要る。`npx mawaru init` が作る（init より前からある repo は自分で足す）
-- 承認画面の上の帯より下を余白なしで全部使える。余白・最大幅・スクロールはビューが決める
-  （縦いっぱいに使うなら `100vh`）。右上の角には mawaru の閉じるボタンが重なるので、大事なものを置かない
+- 承認画面の上の帯より下を余白なしで全部使える。余白・最大幅・スクロールは実装が決める
+  （縦いっぱいに使うなら `100vh`）。右上の角には mawaru の閉じるボタンが重なるので、大事なものを置かない。
+  局面・担当・全員承認の進み具合は mawaru の帯が出し、実装が描かれるのは承認待ちのときだけ
 - mawaru がまとめて（ビルドして）**sandbox iframe の中で動かす**：mawaru のログインや API には届かない。`fetch` も CSP で止まる。
-  要るものは部品キットに頼む：`useViewBridge()` の `fileUrl`（署名付き URL）・`uploadFile`・`copyText`、
-  `useApprovalActions()` の `decide(port, value)`（承認・差し戻し・追加の出口を決める。決定できるとき
-  （`ctx.decision.canDecide`）、人が押した直後だけ通る）・`openRejectDialog()`・`openExitDialog(key, value)`・`close()`。
-  `ApprovalBar` はこれらを使っているので、置くだけなら呼ばなくてよい
-- import できるのは `nodes/human/` の中の相対パス・`react`・`@mawaru/sdk/human` だけ
-  （npm パッケージは不可）。複数の human ノードで使う部品は `nodes/human/_<名前>/` に置ける（`_` 始まりはノードではない）
-- 例外を投げる・まとめられないと、その承認画面は標準に落ちる。URL に `?view=standard` を付けると標準で開ける
+  要るものは `ctx` の口に頼む
+- import できるのは同じディレクトリの中の相対パス・`react`・`@mawaru/sdk/human`・`@mawaru/sdk/components` だけ（npm パッケージは不可）
+- 例外を投げる・まとめられないと、承認画面にエラーと理由が出る
 - 版：program / AI と同じ。公開版は publish 時の commit に固定され、テスト実行は push だけで変わる
-- `cases.ts` — 手元プレビューのケース（`ApprovalViewCase[]` を `export default`。`{ name, input, refs?, nodeName?, phase? }`）
-- 手元プレビュー：`npx mawaru login` のあと、repo ルートで `npx mawaru preview human/<dir>`。push せずに手元のファイルを
-  本番と同じまとめ方・同じ隔離で、承認画面と同じ形で開く（ケースと局面を切り替えられ、承認は送らずに approve に載る値を出す）。
-  保存するたびに送り直し、開いている画面が読み直す。まとめられないと理由を出して exit 1。`--once` は1回送って終わる
+- 試し方：ブランチに push し、ノードの ref にそのブランチを入れてテスト実行する
 
 ## loop（回路）の作成・更新
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mawaru/sdk",
-  "version": "0.40.0",
+  "version": "0.41.0",
   "description": "mawaru 実行 repo の開発 SDK。契約スキーマ（config.json 規約・ループ graph API）の正 ＋ typegen / validate CLI",
   "type": "module",
   "bin": {
@@ -15,6 +15,10 @@
       "types": "./dist/views/human.d.ts",
       "default": "./dist/views/human.js"
     },
+    "./components": {
+      "types": "./dist/views/components.d.ts",
+      "default": "./dist/views/components.js"
+    },
     "./views/slack": {
       "types": "./dist/views/slack.d.ts",
       "default": "./dist/views/slack.js"

package/skills/create-loop/SKILL.md

@@ -49,7 +49,7 @@ secret）でも、**足りない値を推測・生成・空文字で代用しな
   ノード・接続・refs（ループ変数）・hooks の形と、superRefine 内の全整合性ルール（日本語コメント付き）
 - `node_modules/@mawaru/sdk/_schemas/node.ts` — ポートの形（`graphPortSchema`）と key の規則
 - `node_modules/@mawaru/sdk/_schemas/port-spec.ts` — **kind 別の必須ポート構成**（`kindPortsViolation`）と
-  接続の型規則（human の in は実装（nodes/human/）の宣言型、program の in はスキーマ包含 等）
+  接続の型規則（実装（nodes/human/）を指す human は program と同じ宣言型、program の in はスキーマ包含 等）
 - `node_modules/@mawaru/sdk/_schemas/program-manifest.ts` / `ai-manifest.ts` / `human-manifest.ts` — repo 側 config.json の規約
 - 同ディレクトリの `*.test.ts` — 通る graph / 弾かれる graph の実例集として読める
 
@@ -125,7 +125,8 @@ graph の保存（`PUT loops/{loopId}/graph`）は常に下書き（draft）に
    out ポートは outputs の各 key）。human は承認画面、wait は待ち方もここで設定する。
    human は標準の承認画面なら `human.human_dir` を省略する。この repo に専用の承認画面が要るなら
    `nodes/human/<dir>/` に作り（`docs/development.md` の「Human ノード」）、push してから `human.human_dir`（＋任意で `ref`）に
-   ディレクトリ名を入れる（`GET github/humans` が候補を返す）。`human.declaration` は省略してよい（保存時に mawaru が repo から読む）。
+   ディレクトリ名を入れる（`GET github/humans` が候補を返す）。ポートは program と同じく `GET github/humans/:dir/config` の
+   manifest（inputs / outputs）から起こす。
 3. **単体で確かめる**：そのノードだけをテスト実行する。`POST runs/start` に `kind: "test"`・
    `test_scope: "only"`・`start_node_id`（そのノード）・`payload`（サンプル入力。上流を確かめ済みなら
    その output を使う）・`start_by`（ユーザーの user_id。`GET members` で引く。API キー起動では必須）を

package/templates/CLAUDE.md

@@ -9,6 +9,8 @@
 - `nodes/program/<dir>/` — Program ノード（`config.json` ＋ `main.ts`）。`main.ts` は
   `run(input, ctx)` を export し、戻り値は `{ <出口ポートのkey>: <データ> }` の単一キーのオブジェクト
 - `nodes/ai/<dir>/` — AI ノード定義（`config.json`。prompt / model / skills / 入出力スキーマ / env）
+- `nodes/human/<dir>/` — Human ノードの実装（承認画面。`config.json` ＋ `index.tsx`）。`index.tsx` は
+  `export default defineHuman(({ input, out, ctx }) => …)` で、人の操作を `out({ <出口ポートのkey>: <データ> })` で渡す
 - `views/slack/<name>/` — Slack ビュー（実行中・承認待ち・完了メッセージの本文）。`index.ts` ＋ 手元プレビュー用の `cases.ts`
 - `.github/workflows/mawaru-runner.yml` — mawaru 所有の実行シム。**編集しない**
   （`npx @mawaru/sdk init` が再生成する）

package/views/_humanProps.ts

@@ -0,0 +1,27 @@
+import type { FileRef } from "./_parts/fileRef.js"
+import type { HumanProps } from "./human.js"
+import type { HumanViewData } from "./protocol.js"
+
+// human ノードの実装に渡す props を組み立てる（iframe の中の実行部分と、mawaru の中の標準の承認画面で同じものを使う）。
+// 関数の中身は呼ぶ側が差す：iframe の中はホストへの頼みごと、ホストの画面は API を直接呼ぶ
+export type HumanOps = {
+  out: (output: Record<string, unknown>) => Promise<void>
+  fetchFileUrl: (file: FileRef) => Promise<string>
+  uploadFile: (file: File) => Promise<FileRef>
+  writeText: (text: string) => Promise<void>
+}
+
+export const humanPropsOf = (
+  data: HumanViewData,
+  ops: HumanOps,
+): HumanProps => ({
+  input: data.input,
+  out: ops.out,
+  ctx: {
+    input: { schema: data.inputSchema, fetchFileUrl: ops.fetchFileUrl },
+    output: { schema: data.outputSchema, uploadFile: ops.uploadFile },
+    clipboard: { writeText: ops.writeText },
+    refs: (data.refs ?? {}) as Record<string, unknown>,
+    step: { isAssignee: data.isAssignee, editable: data.editable },
+  },
+})

package/views/components.ts

@@ -0,0 +1,16 @@
+// 共通の部品（`@mawaru/sdk/components`）。human ノードの約束（`@mawaru/sdk/human`）には依存しない。
+// mawaru の画面と顧客 repo の human ノードの実装が同じ部品を使う（mawaru が顧客 repo の実装をまとめるとき、
+// mawaru の今の版のこの部品を同梱する）。ファイルの表示・アップロードは、mawaru の画面ではホストの口、
+// sandbox iframe の中では mawaru の承認画面への頼みごととして裏で差し込まれる（_bridge.tsx）。
+// **公開 API**：部品の props は後方互換でしか変えない
+export { documentCardStyle } from "./_parts/DocumentCard.js"
+export { FilePreview } from "./_parts/FilePreview.js"
+export { type FileRef, isFileRef } from "./_parts/fileRef.js"
+export { isUrl, Linkify, linkify } from "./_parts/Linkify.js"
+export { isLongText, Markdown, useAutoGrow } from "./_parts/Markdown.js"
+export {
+  asFormSchema,
+  type JsonSchema as FormSchema,
+  SchemaForm,
+} from "./_parts/SchemaForm.js"
+export { NARROW_WIDTH, useNarrow } from "./_parts/useNarrow.js"

package/views/host.ts

@@ -1,11 +1,15 @@
 import { z } from "zod"
 import { VIEW_MESSAGE_TAG } from "./protocol.js"
 
-export { ApprovalActionsProvider } from "./_approvalActions.js"
 // ホスト（mawaru の画面）だけが使うもの（公開 API ではない）：sandbox iframe からのメッセージを確かめる形
-// （protocol.ts の型と同じ。iframe の中は信用できないコードなので、形を確かめてから使う）と、
-// ビューに頼む口を差す提供部品
-export { ViewBridgeProvider } from "./_bridge.js"
+// （protocol.ts の型と同じ。iframe の中は信用できないコードなので、形を確かめてから使う）、
+// 部品が裏で使う口を差す提供部品、human ノードの実装に渡す props の組み立て（標準の承認画面も同じものを使う）
+export {
+  useViewBridge,
+  type ViewBridge,
+  ViewBridgeProvider,
+} from "./_bridge.js"
+export { type HumanOps, humanPropsOf } from "./_humanProps.js"
 export * from "./protocol.js"
 
 const tag = z.literal(VIEW_MESSAGE_TAG)
@@ -17,7 +21,7 @@ export const viewToHostSchema = z.discriminatedUnion("type", [
     tag,
     type: z.literal("request"),
     id: z.number().int(),
-    method: z.string(),
+    method: z.enum(["out", "fetchFileUrl", "uploadFile", "writeText"]),
     args: z.unknown(),
   }),
 ])