@mawaru/sdk 0.39.0 → 0.41.0

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/dist/{slack-view.d.ts → views/slack.d.ts}

@@ -1,4 +1,4 @@
-import type { JsonSchema, NodeKind } from "./_schemas/node.js";
+import type { JsonSchema, NodeKind } from "../_schemas/node.js";
 export type SlackBlocks = unknown[];
 export type FileRef = {
     path: string;

package/docs/development.md

@@ -19,6 +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
 skills/<dir>/      # AI ノードが参照する skill（SKILL.md）
 views/
   slack/<name>/    # Slack ビュー：index.ts（＋手元プレビュー用の cases.ts）
@@ -81,10 +82,10 @@ views/
   ディレクトリ名で出る）。タイトル行・追加出口のボタン・投稿は mawaru が描く
 - `index.ts` — `export default { files?, renderRunning?, renderCompleted? } satisfies SlackView<入力の型>`。
   契約（型・ctx の中身・決定ボタンの `decisionActionId` / `decisionFormActionId`）の正は
-  `@mawaru/sdk/slack-view`。実装した関数の面だけが変わる
+  `@mawaru/sdk/views/slack`。実装した関数の面だけが変わる
 - **純関数**にする：mawaru が隔離環境（QuickJS）で動かすので、`fetch` / `process` / `require` / タイマー /
   `console` は無い。1回の呼び出しは 200ms・32MB まで。ctx も戻り値も JSON で受け渡す
-- import できるのは同じディレクトリ内の相対パスと `@mawaru/sdk/slack-view` だけ（npm パッケージは不可）。
+- import できるのは同じディレクトリ内の相対パスと `@mawaru/sdk/views/slack` だけ（npm パッケージは不可）。
   ビルドしない（mawaru が TypeScript の型を外して読む。`enum` など型を外すだけで JS にならない書き方は不可）
 - 入力は崩れて届くことがある（`input` が `null` 等）。例外を投げない書き方にする。失敗すると、承認待ちは
   承認ボタンだけ・完了は1行のフォールバックになる
@@ -99,6 +100,42 @@ views/
   - 端末に1通ごとの結果が出る（`✔` 成功・`⚠` 描画に失敗して理由つき・`–` 未実装の面）。失敗が1つでもあれば exit 1。
     ビューを直したら同じコマンドで送り直して確かめる
 
+## Human ノード（`nodes/human/<dir>/`）
+
+- 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 の閉じるボタンが重なるので、大事なものを置かない。
+  局面・担当・全員承認の進み具合は mawaru の帯が出し、実装が描かれるのは承認待ちのときだけ
+- mawaru がまとめて（ビルドして）**sandbox iframe の中で動かす**：mawaru のログインや API には届かない。`fetch` も CSP で止まる。
+  要るものは `ctx` の口に頼む
+- import できるのは同じディレクトリの中の相対パス・`react`・`@mawaru/sdk/human`・`@mawaru/sdk/components` だけ（npm パッケージは不可）
+- 例外を投げる・まとめられないと、承認画面にエラーと理由が出る
+- 版：program / AI と同じ。公開版は publish 時の commit に固定され、テスト実行は push だけで変わる
+- 試し方：ブランチに push し、ノードの ref にそのブランチを入れてテスト実行する
+
 ## loop（回路）の作成・更新
 
 - `.claude/skills/create-loop` スキルに従う（graph API の契約は `_schemas/graph.ts` が正）

package/index.ts

@@ -6,6 +6,7 @@ export * from "./_schemas/duplicate-selection.js"
 export * from "./_schemas/extract-component.js"
 export * from "./_schemas/graph.js"
 export * from "./_schemas/hook-manifest.js"
+export * from "./_schemas/human-manifest.js"
 export * from "./_schemas/node.js"
 export * from "./_schemas/port-spec.js"
 export * from "./_schemas/program-manifest.js"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mawaru/sdk",
-  "version": "0.39.0",
+  "version": "0.41.0",
   "description": "mawaru 実行 repo の開発 SDK。契約スキーマ（config.json 規約・ループ graph API）の正 ＋ typegen / validate CLI",
   "type": "module",
   "bin": {
@@ -11,9 +11,29 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./human": {
+      "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"
+    },
     "./slack-view": {
-      "types": "./dist/slack-view.d.ts",
-      "default": "./dist/slack-view.js"
+      "types": "./dist/views/slack.d.ts",
+      "default": "./dist/views/slack.js"
+    },
+    "./views/runtime": {
+      "types": "./dist/views/runtime.d.ts",
+      "default": "./dist/views/runtime.js"
+    },
+    "./views/host": {
+      "types": "./dist/views/host.d.ts",
+      "default": "./dist/views/host.js"
     }
   },
   "files": [
@@ -23,7 +43,7 @@
     "docs",
     "_schemas",
     "index.ts",
-    "slack-view.ts"
+    "views"
   ],
   "engines": {
     "node": ">=20"
@@ -32,8 +52,24 @@
     "zod": "^4.4.3",
     "zod-from-json-schema": "^0.5.3"
   },
+  "peerDependencies": {
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@types/node": "^26.1.0",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
     "typescript": "^6.0.3",
     "vitest": "^4.1.9"
   },

package/skills/create-loop/SKILL.md

@@ -49,8 +49,8 @@ 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 は承認ビューの宣言型、program の in はスキーマ包含 等）
-- `node_modules/@mawaru/sdk/_schemas/program-manifest.ts` / `ai-manifest.ts` — repo 側 config.json の規約
+  接続の型規則（実装（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 の実例集として読める
 
 ## API（パスとボディは openapi.json が正）
@@ -122,7 +122,11 @@ graph の保存（`PUT loops/{loopId}/graph`）は常に下書き（draft）に
    graph 保存の書き戻しと食い違って 409 になり、テスト実行も古い中身で走る）。
 2. **ノードに結びつける**：graph の該当ノードに `program.program_dir` / `ai.ai_dir` を設定し、
    ports を config.json の inputs / outputs の写しにして保存する（in ポート key は `in`、
-   out ポートは outputs の各 key）。human は承認ビュー、wait は待ち方もここで設定する。
+   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` が候補を返す）。ポートは 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/_bridge.tsx

@@ -0,0 +1,36 @@
+import { createContext, type ReactNode, useContext } from "react"
+import type { FileRef } from "./_parts/fileRef.js"
+
+// ビューがホスト（mawaru の画面）に頼めること。顧客 repo のビューは sandbox iframe の中で動き、
+// API を叩けない（認証が付かない）ので、要るものはここ経由でホストに頼む
+// （docs/tasks/wip/承認ビューの顧客repo配置.md の「ビューがホストに頼めること」）。
+// ホストの画面の中では API を直接呼ぶ実装を、iframe の中では postMessage の実装を差す。
+// 部品（FilePreview・SchemaForm のファイル欄）もこれを使うので、どちらで描いても同じに動く
+export type ViewBridge = {
+  // Storage の署名付き URL（private バケットなので描画のたびに取る）
+  fileUrl: (file: FileRef) => Promise<string>
+  // ファイルを上げて参照を返す（SchemaForm のファイル欄と同じアップロード先）
+  uploadFile: (file: File) => Promise<FileRef>
+  // クリップボードに書く（sandbox の中からは書けない）
+  copyText: (text: string) => Promise<void>
+}
+
+const ViewBridgeContext = createContext<ViewBridge | null>(null)
+
+export const ViewBridgeProvider = ({
+  bridge,
+  children,
+}: {
+  bridge: ViewBridge
+  children: ReactNode
+}) => (
+  <ViewBridgeContext.Provider value={bridge}>
+    {children}
+  </ViewBridgeContext.Provider>
+)
+
+export const useViewBridge = (): ViewBridge => {
+  const bridge = useContext(ViewBridgeContext)
+  if (!bridge) throw new Error("ViewBridgeProvider の中で使ってください")
+  return bridge
+}

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/_parts/DocumentCard.ts

@@ -0,0 +1,18 @@
+import type { CSSProperties } from "react"
+
+// 承認画面の「書類」カードの枠（標準ビュー・回答レビュー・お問い合わせ回答で同じ形）。
+// 狭い幅（useNarrow）では左右の余白を詰めて本文の幅を確保する
+export const documentCardStyle = (narrow: boolean): CSSProperties => ({
+  maxWidth: "720px",
+  margin: "0 auto",
+  display: "flex",
+  flexDirection: "column",
+  gap: "var(--space-4)",
+  background: "var(--surface)",
+  border: "var(--border-w) solid var(--border)",
+  borderRadius: "var(--radius-m)",
+  boxShadow: "var(--shadow)",
+  padding: narrow
+    ? "var(--space-5) var(--space-4) var(--space-6)"
+    : "var(--space-6) var(--space-10) var(--space-8)",
+})

package/views/_parts/FilePreview.tsx

@@ -0,0 +1,180 @@
+import { type CSSProperties, useEffect, useState } from "react"
+import { useViewBridge } from "../_bridge.js"
+import type { FileRef } from "./fileRef.js"
+
+// file 参照の閲覧表示：private バケットなので描画のたびに閲覧用署名 URL を（ホストに頼んで）取り、
+// 画像（GIF 含む）と PDF はそのままインラインで見せる。それ以外は名前チップのリンクにする。
+// NodeIoCards の IoFileItem と同じ経路だが、こちらは「見て判断する」ための大きさで出す。
+// PDF は請求書・契約書のように「現物を見て承認する」書類で必要になる（承認画面の中で
+// 完結させたいので、別タブへ飛ばさない）
+
+const chipStyle: CSSProperties = {
+  display: "inline-flex",
+  alignItems: "center",
+  gap: "4px",
+  maxWidth: "100%",
+  border: "var(--border-w) solid var(--border)",
+  borderRadius: "var(--radius-s)",
+  background: "var(--surface-2)",
+  padding: "2px 8px",
+  fontSize: "var(--text-xs)",
+  color: "var(--ink)",
+  textDecoration: "none",
+}
+
+// mime_type は上流が入れてくれないことがあるので拡張子でも判定する
+const isImageFile = (file: FileRef): boolean =>
+  file.mime_type?.startsWith("image/") ??
+  /\.(gif|png|jpe?g|webp|avif|svg)$/i.test(file.name)
+
+const isPdfFile = (file: FileRef): boolean =>
+  file.mime_type === "application/pdf" || /\.pdf$/i.test(file.name)
+
+export const FilePreview = ({
+  file,
+  maxHeight = "420px",
+}: {
+  file: FileRef
+  maxHeight?: string
+}) => {
+  const bridge = useViewBridge()
+  const [url, setUrl] = useState<string | null>(null)
+  // 署名 URL を取れなかった（ファイルが消えた・パスが違う）ことを「読み込み中」と
+  // 区別する：失敗を黙って読み込み中のまま固めると、原因が画面から分からない
+  const [failed, setFailed] = useState(false)
+  useEffect(() => {
+    let alive = true
+    setUrl(null)
+    setFailed(false)
+    bridge
+      .fileUrl(file)
+      .then((signed) => {
+        if (alive) setUrl(signed)
+      })
+      .catch(() => {
+        if (alive) setFailed(true)
+      })
+    return () => {
+      alive = false
+    }
+  }, [bridge, file])
+
+  const caption = (
+    <span style={{ fontSize: "var(--text-xs)", color: "var(--muted)" }}>
+      {file.name}
+    </span>
+  )
+
+  // PDF はブラウザ内蔵ビューアに任せる（依存を増やさない）。maxHeight は画像では
+  // 上限だが、PDF では枠の高さそのものになる（内側でスクロールさせるため）
+  if (isPdfFile(file)) {
+    return (
+      <figure style={{ margin: 0, display: "grid", gap: "var(--space-1)" }}>
+        {url ? (
+          <iframe
+            src={url}
+            title={file.name}
+            style={{
+              display: "block",
+              width: "100%",
+              height: maxHeight,
+              background: "var(--surface-2)",
+              borderRadius: "var(--radius-s)",
+              border: "var(--border-w) solid var(--border)",
+            }}
+          />
+        ) : (
+          <div
+            style={{
+              display: "grid",
+              placeItems: "center",
+              height: maxHeight,
+              background: "var(--surface-2)",
+              borderRadius: "var(--radius-s)",
+              border: "var(--border-w) dashed var(--border)",
+              fontSize: "var(--text-xs)",
+              color: "var(--muted)",
+              textAlign: "center",
+              padding: "0 var(--space-4)",
+            }}
+          >
+            {failed ? "ファイルを読み込めませんでした" : "読み込み中…"}
+          </div>
+        )}
+        <figcaption
+          style={{
+            display: "flex",
+            justifyContent: "space-between",
+            gap: "var(--space-2)",
+          }}
+        >
+          {caption}
+          {url && (
+            <a
+              href={url}
+              target="_blank"
+              rel="noreferrer"
+              style={{ fontSize: "var(--text-xs)", color: "var(--muted)" }}
+            >
+              別タブで開く
+            </a>
+          )}
+        </figcaption>
+      </figure>
+    )
+  }
+
+  if (!isImageFile(file)) {
+    return url ? (
+      <a href={url} target="_blank" rel="noreferrer" style={chipStyle}>
+        <span aria-hidden="true">📎</span>
+        {file.name}
+      </a>
+    ) : (
+      <span style={chipStyle}>
+        <span aria-hidden="true">📎</span>
+        {file.name}
+      </span>
+    )
+  }
+
+  return (
+    <figure style={{ margin: 0, display: "grid", gap: "var(--space-1)" }}>
+      {url ? (
+        <a href={url} target="_blank" rel="noreferrer">
+          <img
+            src={url}
+            alt={file.name}
+            style={{
+              display: "block",
+              width: "100%",
+              maxHeight,
+              objectFit: "contain",
+              background: "var(--surface-2)",
+              borderRadius: "var(--radius-s)",
+              border: "var(--border-w) solid var(--border)",
+            }}
+          />
+        </a>
+      ) : (
+        <div
+          style={{
+            display: "grid",
+            placeItems: "center",
+            height: "160px",
+            background: "var(--surface-2)",
+            borderRadius: "var(--radius-s)",
+            border: "var(--border-w) dashed var(--border)",
+            fontSize: "var(--text-xs)",
+            color: "var(--muted)",
+            textAlign: "center",
+            padding: "0 var(--space-4)",
+          }}
+        >
+          {failed ? "画像を読み込めませんでした" : "読み込み中…"}
+        </div>
+      )}
+      <figcaption>{caption}</figcaption>
+    </figure>
+  )
+}

package/views/_parts/Linkify.test.ts

@@ -0,0 +1,40 @@
+import { isValidElement } from "react"
+import { describe, expect, it } from "vitest"
+import { isUrl, linkify } from "./Linkify.js"
+
+const hrefs = (text: string) =>
+  linkify(text).flatMap((node) =>
+    isValidElement<{ href: string }>(node) ? [node.props.href] : [],
+  )
+
+describe("linkify", () => {
+  it("素の URL をリンクにし、前後の文字はそのまま残す", () => {
+    const nodes = linkify("PR: https://github.com/a/b/pull/1 を見て")
+    expect(nodes[0]).toBe("PR: ")
+    expect(hrefs("PR: https://github.com/a/b/pull/1 を見て")).toEqual([
+      "https://github.com/a/b/pull/1",
+    ])
+    expect(nodes[2]).toBe(" を見て")
+  })
+
+  it("引用符・括弧・末尾の句読点は URL に含めない", () => {
+    expect(hrefs('"https://example.com/x"')).toEqual(["https://example.com/x"])
+    expect(hrefs("（https://example.com/y）")).toEqual([
+      "https://example.com/y",
+    ])
+    expect(hrefs("see https://example.com/z.")).toEqual([
+      "https://example.com/z",
+    ])
+  })
+
+  it("URL が無ければ元の文字列だけ", () => {
+    expect(linkify("ただの文")).toEqual(["ただの文"])
+  })
+})
+
+describe("isUrl", () => {
+  it("文字列全体が URL のときだけ true", () => {
+    expect(isUrl("https://github.com/PathLight-jp/x/pull/12")).toBe(true)
+    expect(isUrl("詳細は https://example.com")).toBe(false)
+  })
+})

package/views/_parts/Linkify.tsx

@@ -0,0 +1,40 @@
+import type { ReactNode } from "react"
+
+// テキスト中の素の URL（http/https）をクリックできるリンクにする。
+// 値の表示（I/O・タイムライン・承認ビュー等）はどこでもこれを通す。
+// 引用符・括弧・全角の区切りは URL に含めず、末尾の句読点も外す
+const urlPattern = /https?:\/\/[^\s"'<>()[\]{}（）「」『』【】、。]+/g
+const trailingPunct = /[.,;:!?]+$/
+
+/** 文字列全体が1つの URL か */
+export const isUrl = (value: string): boolean =>
+  /^https?:\/\/\S+$/.test(value.trim())
+
+export const linkify = (text: string, prefix = ""): ReactNode[] => {
+  const nodes: ReactNode[] = []
+  let last = 0
+  for (const match of text.matchAll(urlPattern)) {
+    const start = match.index ?? 0
+    const url = match[0].replace(trailingPunct, "")
+    if (url.length <= "https://".length) continue
+    if (start > last) nodes.push(text.slice(last, start))
+    nodes.push(
+      <a
+        key={`${prefix}${start}`}
+        href={url}
+        target="_blank"
+        rel="noreferrer"
+        // 行クリックで選択・開閉する親の中でも、リンクはリンクとして開く
+        onClick={(e) => e.stopPropagation()}
+        style={{ overflowWrap: "anywhere" }}
+      >
+        {url}
+      </a>,
+    )
+    last = start + url.length
+  }
+  if (last < text.length) nodes.push(text.slice(last))
+  return nodes
+}
+
+export const Linkify = ({ text }: { text: string }) => <>{linkify(text)}</>