@f12o/markable 2026.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hirohito FUJITA
+
+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.ja.md

@@ -0,0 +1,79 @@
+# markable
+
+あらゆるものをマーク可能にします。
+
+`markable` は、既存アプリの実装を大きく変えずに、構造化されたフィードバック、レビューコメント、書き換え指示を成果物へ紐づけるためのヘッドレスなインタラクションレイヤーです。
+
+## モード
+
+- **dev / review**: 開発者向けのレビュー注釈を保存し、エージェントやリライトツールが利用できる JSON として扱います。
+- **prod / feedback**: ユーザー向けのフィードバックや問い合わせを、URL・選択範囲・ビューポート・任意コンテキストと一緒に収集します。
+
+## インストール
+
+```bash
+npm install @f12o/markable
+```
+
+主なサブパスエクスポートは次のとおりです。
+
+```ts
+import { createMarkable } from "@f12o/markable/core";
+import { createDomAdapter } from "@f12o/markable/dom";
+import { markable } from "@f12o/markable/vite";
+```
+
+## Vite での使い方
+
+```ts
+import { defineConfig } from "vite";
+import { markable } from "@f12o/markable/vite";
+
+export default defineConfig({
+  plugins: [
+    markable({
+      mode: "auto",
+      commentsFile: ".markable/comments.json",
+      endpoint: "/__markable/comments",
+    }),
+  ],
+});
+```
+
+`mode: "auto"` は Vite の開発時に review モード、本番ビルド時に feedback モードへ解決されます。
+
+## UI の使い方
+
+画面右下のフローティングボタンから composer を開きます。
+
+- ハイライトされた要素をクリックすると、その DOM 要素にマークを紐づけます。
+- 空白部分をドラッグすると、矩形の画面範囲にマークを紐づけます。
+- 対象を選ばずに保存すると、ページ全体へのフィードバックとして記録します。
+- ボタン、composer のタイトル、最近のマーク一覧の見出しはドラッグ可能です。UI が選択したい要素に重なった場合は、任意の場所へ移動できます。
+
+開発サーバーでは、投稿された注釈が `.markable/comments.json` に保存されます。静的な GitHub Pages 配信では POST 先がないため、外部エンドポイントを設定しない限りセッション内の表示に留まります。
+
+## デモ
+
+軽量な Vue 3 + Vite Todo デモ:
+
+```bash
+pnpm install
+pnpm build
+pnpm --filter @f12o/markable-vite-todo-demo dev
+```
+
+より実践的な React ダッシュボードデモ:
+
+```bash
+pnpm --filter @f12o/markable-shadcn-admin-demo dev
+pnpm --filter @f12o/markable-shadcn-admin-demo build
+```
+
+GitHub Pages では次の URL でデモを確認できます。
+
+```text
+https://f4ah6o.github.io/markable/
+https://f4ah6o.github.io/markable/vue-todo/
+https://f4ah6o.github.io/markable/shadcn-admin/
+```

package/README.md

@@ -0,0 +1,160 @@
+# markable
+
+[日本語版](README.ja.md)
+
+Make anything markable.
+
+`markable` is a headless interaction layer for attaching structured feedback, review comments, and rewrite annotations to artifacts without changing the existing app implementation.
+
+It is designed to work in two modes:
+
+- **dev**: developer-oriented review annotations that can be consumed by agents and rewrite tools.
+- **prod**: user-facing feedback and inquiry capture with URL, selection, viewport, and optional context.
+
+## Package shape
+
+The intended npm entry point is:
+
+```bash
+npm install @f12o/markable
+```
+
+Subpath exports are used for integrations:
+
+```ts
+import { createMarkable } from "@f12o/markable/core";
+import { createDomAdapter } from "@f12o/markable/dom";
+import { markable } from "@f12o/markable/vite";
+```
+
+## Vite usage
+
+```ts
+import { defineConfig } from "vite";
+import { markable } from "@f12o/markable/vite";
+
+export default defineConfig({
+  plugins: [
+    markable({
+      mode: process.env.NODE_ENV === "production" ? "feedback" : "review",
+      commentsFile: ".markable/comments.json",
+      endpoint: "/__markable/comments",
+    }),
+  ],
+});
+```
+
+## Vite+ compatibility
+
+Vite+ is expected to run normal Vite plugins when it loads a Vite-compatible config. `markable` keeps the integration as a standard Vite plugin instead of exposing a Vite+-specific API.
+
+Initial compatibility target:
+
+```bash
+vp dev
+vp build
+```
+
+The plugin currently uses standard Vite hooks:
+
+```text
+transformIndexHtml
+configureServer
+resolveId
+load
+```
+
+## Core idea
+
+```text
+artifact
+  -> mark target
+  -> annotate / comment / feedback
+  -> structured event
+  -> ticket / JSON / agent input
+  -> rewrite / resolve / follow-up
+```
+
+`markable` does not own your UI. The core is headless. DOM and Vite integrations provide capture and injection only.
+
+## Current status
+
+Initial scaffold.
+
+## Inspiration
+
+The production feedback selection UX is inspired by [`u-ichi/reviewable-html-workbench`](https://github.com/u-ichi/reviewable-html-workbench), particularly its clear review state, contextual highlighting, and visually anchored comments. `markable` generalizes that interaction pattern for production web app feedback while keeping the core package headless.
+
+## Demo app
+
+A lightweight Vue 3 + Vite Todo demo lives in `examples/vite-todo`. It is intentionally small so the markable integration is easy to inspect:
+
+```bash
+pnpm install
+pnpm build
+pnpm --filter @f12o/markable-vite-todo-demo dev
+```
+
+The demo config uses the package Vite plugin directly:
+
+```ts
+markable({
+  mode: "auto",
+  commentsFile: ".markable/comments.json",
+  endpoint: "/__markable/comments",
+});
+```
+
+In Vite development mode, `mode: "auto"` resolves to review mode. Use the floating Mark button to open a composer. Practical page elements highlight automatically as you move over them; click a highlighted element to attach the mark to that DOM element, drag an empty page area to attach it to a rectangular screen region, or save without choosing a target to attach it to the current page. The dev server endpoint writes structured annotation JSON to `.markable/comments.json` inside the demo app.
+
+In production builds, `mode: "auto"` resolves to feedback mode. The floating Feedback button opens a user-facing feedback panel with Feedback and Question tabs, the same automatic element and box targeting behavior, and an in-session list of recent submissions. Captured context includes URL, title, viewport, user agent, the active tab intent, and the optional selected element or rectangle.
+
+### shadcn-admin example
+
+A larger React dashboard example lives in `examples/shadcn-admin`. It vendors [`satnaing/shadcn-admin`](https://github.com/satnaing/shadcn-admin) at commit `e16c87f213a5ba5e45964e9b67c792105ec74d26` and adds the markable Vite plugin so the overlay can be exercised against a realistic shadcn UI:
+
+```bash
+pnpm install
+pnpm --filter @f12o/markable-shadcn-admin-demo dev
+pnpm --filter @f12o/markable-shadcn-admin-demo build
+```
+
+The example config uses the same local development endpoint as the Todo demo:
+
+```ts
+markable({
+  mode: "auto",
+  commentsFile: ".markable/comments.json",
+  endpoint: "/__markable/comments",
+});
+```
+
+In local development, submitted marks are persisted to `examples/shadcn-admin/.markable/comments.json`.
+
+### GitHub Pages deployment
+
+The `Deploy demo to GitHub Pages` workflow builds the package, builds the examples, generates an example index, and publishes the static output to GitHub Pages at:
+
+```text
+https://f4ah6o.github.io/markable/
+https://f4ah6o.github.io/markable/vue-todo/
+https://f4ah6o.github.io/markable/shadcn-admin/
+```
+
+The index page is generated from `examples/examples.json` by `scripts/build-pages-index.mjs`, so new examples can be added to the listing by updating the manifest.
+
+GitHub Pages is static hosting, so it can demonstrate the example apps and injected feedback overlay but cannot persist POSTed feedback to `/.markable` or `/.json` files. For public static deployments, treat submitted feedback as local/session-only unless a remote endpoint is configured.
+
+### Cloudflare Workers follow-up
+
+For persistent production feedback, point the markable endpoint at a Worker route such as `/api/feedback`:
+
+```text
+browser
+  -> markable feedback UI
+  -> /api/feedback
+  -> Cloudflare Worker
+  -> D1, KV, R2, GitHub Issues, a queue, or a webhook
+```
+
+That follow-up can keep the static GitHub Pages demo lightweight while adding real storage, notification, or issue creation behind a Worker-backed endpoint.

package/dist/chunk-LSUELO2A.js

@@ -0,0 +1,48 @@
+// src/core.ts
+function createMarkable(options) {
+  const now = options.now ?? (() => /* @__PURE__ */ new Date());
+  const idFactory = options.idFactory ?? defaultIdFactory;
+  return {
+    mode: options.mode,
+    load() {
+      return options.store.load();
+    },
+    async submit(message) {
+      const target = options.adapter.getTarget();
+      if (!target) {
+        throw new Error("markable: no active target");
+      }
+      const timestamp = now().toISOString();
+      const annotation = {
+        id: idFactory(),
+        mode: options.mode,
+        target,
+        message,
+        status: "open",
+        context: options.adapter.getContext?.(),
+        createdAt: timestamp,
+        updatedAt: timestamp
+      };
+      await options.store.save(annotation);
+      options.adapter.clearSelection?.();
+      return annotation;
+    },
+    async updateStatus(id, status) {
+      if (!options.store.update) {
+        throw new Error("markable: store does not support update");
+      }
+      await options.store.update(id, {
+        status,
+        updatedAt: now().toISOString()
+      });
+    }
+  };
+}
+function defaultIdFactory() {
+  const random = Math.random().toString(36).slice(2, 10);
+  return `mark-${random}`;
+}
+
+export {
+  createMarkable
+};

package/dist/chunk-ROXJDUMI.js

@@ -0,0 +1,89 @@
+// src/dom.ts
+function createDomAdapter(options = {}) {
+  const root = options.root ?? document;
+  const doc = root instanceof Document ? root : root.ownerDocument;
+  return {
+    getTarget() {
+      const selection = doc.getSelection();
+      if (!selection || selection.rangeCount === 0 || selection.isCollapsed) {
+        return null;
+      }
+      const range = selection.getRangeAt(0);
+      const container = nearestElement(range.commonAncestorContainer);
+      if (!container) {
+        return null;
+      }
+      const rect = range.getBoundingClientRect();
+      return {
+        kind: "dom_range",
+        locator: {
+          selector: selectorFor(container),
+          startOffset: range.startOffset,
+          endOffset: range.endOffset
+        },
+        quote: selection.toString(),
+        rect: {
+          x: rect.x,
+          y: rect.y,
+          width: rect.width,
+          height: rect.height
+        }
+      };
+    },
+    getContext() {
+      return {
+        url: globalThis.location?.href,
+        title: doc.title,
+        viewport: {
+          width: globalThis.innerWidth,
+          height: globalThis.innerHeight
+        },
+        userAgent: globalThis.navigator?.userAgent
+      };
+    },
+    clearSelection() {
+      doc.getSelection()?.removeAllRanges();
+    }
+  };
+}
+function nearestElement(node) {
+  if (node.nodeType === Node.ELEMENT_NODE) {
+    return node;
+  }
+  return node.parentElement;
+}
+function selectorFor(element) {
+  if (element.id) {
+    return `#${cssEscape(element.id)}`;
+  }
+  const parts = [];
+  let current = element;
+  while (current && current.nodeType === Node.ELEMENT_NODE && current !== document.body) {
+    const currentElement = current;
+    const tag = currentElement.tagName.toLowerCase();
+    const parent = currentElement.parentElement;
+    if (!parent) {
+      parts.unshift(tag);
+      break;
+    }
+    const siblings = Array.from(parent.children).filter(
+      (child) => child.tagName === currentElement.tagName
+    );
+    if (siblings.length === 1) {
+      parts.unshift(tag);
+    } else {
+      const index = siblings.indexOf(currentElement) + 1;
+      parts.unshift(`${tag}:nth-of-type(${index})`);
+    }
+    current = parent;
+  }
+  return parts.join(" > ");
+}
+function cssEscape(value) {
+  const escape = globalThis.CSS?.escape;
+  return escape ? escape(value) : value.replace(/[^a-zA-Z0-9_-]/g, "\\$&");
+}
+
+export {
+  createDomAdapter
+};

package/dist/core.d.ts

@@ -0,0 +1,63 @@
+type MarkableMode = "review" | "feedback";
+type MarkableTargetKind = "dom_range" | "dom_element" | "text_range" | "line_range" | "cell_range" | "bbox" | "node" | "edge";
+type MarkableStatus = "open" | "agent_replied" | "applied" | "rejected" | "needs_user_reply" | "resolved";
+interface MarkableRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface MarkableTarget {
+    kind: MarkableTargetKind;
+    locator: Record<string, unknown>;
+    quote?: string;
+    prefix?: string;
+    suffix?: string;
+    rect?: MarkableRect;
+}
+interface MarkableContext {
+    url?: string;
+    title?: string;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    userAgent?: string;
+    [key: string]: unknown;
+}
+interface MarkableAnnotation {
+    id: string;
+    mode: MarkableMode;
+    target: MarkableTarget;
+    message: string;
+    status: MarkableStatus;
+    context?: MarkableContext;
+    createdAt: string;
+    updatedAt: string;
+}
+interface MarkableStore {
+    load(): Promise<MarkableAnnotation[]>;
+    save(annotation: MarkableAnnotation): Promise<void>;
+    update?(id: string, patch: Partial<MarkableAnnotation>): Promise<void>;
+}
+interface MarkableAdapter {
+    getTarget(): MarkableTarget | null;
+    getContext?(): MarkableContext;
+    clearSelection?(): void;
+}
+interface CreateMarkableOptions {
+    mode: MarkableMode;
+    adapter: MarkableAdapter;
+    store: MarkableStore;
+    idFactory?: () => string;
+    now?: () => Date;
+}
+interface MarkableRuntime {
+    mode: MarkableMode;
+    load(): Promise<MarkableAnnotation[]>;
+    submit(message: string): Promise<MarkableAnnotation>;
+    updateStatus(id: string, status: MarkableStatus): Promise<void>;
+}
+declare function createMarkable(options: CreateMarkableOptions): MarkableRuntime;
+
+export { type CreateMarkableOptions, type MarkableAdapter, type MarkableAnnotation, type MarkableContext, type MarkableMode, type MarkableRect, type MarkableRuntime, type MarkableStatus, type MarkableStore, type MarkableTarget, type MarkableTargetKind, createMarkable };

package/dist/core.js

@@ -0,0 +1,6 @@
+import {
+  createMarkable
+} from "./chunk-LSUELO2A.js";
+export {
+  createMarkable
+};

package/dist/dom.d.ts

@@ -0,0 +1,8 @@
+import { MarkableAdapter } from './core.js';
+
+interface DomAdapterOptions {
+    root?: Document | HTMLElement;
+}
+declare function createDomAdapter(options?: DomAdapterOptions): MarkableAdapter;
+
+export { type DomAdapterOptions, createDomAdapter };

package/dist/dom.js

@@ -0,0 +1,6 @@
+import {
+  createDomAdapter
+} from "./chunk-ROXJDUMI.js";
+export {
+  createDomAdapter
+};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { CreateMarkableOptions, MarkableAdapter, MarkableAnnotation, MarkableContext, MarkableMode, MarkableRect, MarkableRuntime, MarkableStatus, MarkableStore, MarkableTarget, MarkableTargetKind, createMarkable } from './core.js';
+export { DomAdapterOptions, createDomAdapter } from './dom.js';

package/dist/index.js

@@ -0,0 +1,10 @@
+import {
+  createMarkable
+} from "./chunk-LSUELO2A.js";
+import {
+  createDomAdapter
+} from "./chunk-ROXJDUMI.js";
+export {
+  createDomAdapter,
+  createMarkable
+};

package/dist/vite.d.ts

@@ -0,0 +1,12 @@
+import { Plugin } from 'vite';
+import { MarkableMode } from './core.js';
+
+interface MarkableViteOptions {
+    mode?: MarkableMode | "auto";
+    commentsFile?: string;
+    endpoint?: string;
+    inject?: boolean;
+}
+declare function markable(options?: MarkableViteOptions): Plugin;
+
+export { type MarkableViteOptions, markable };

package/dist/vite.js

@@ -0,0 +1,442 @@
+// src/vite.ts
+import fs from "fs/promises";
+import path from "path";
+function markable(options = {}) {
+  const endpoint = options.endpoint ?? "/__markable/comments";
+  const commentsFile = options.commentsFile ?? ".markable/comments.json";
+  const inject = options.inject ?? true;
+  let root = process.cwd();
+  let resolvedMode = "review";
+  return {
+    name: "markable",
+    configResolved(config) {
+      root = config.root;
+      resolvedMode = resolveMode(options.mode, config.mode);
+    },
+    transformIndexHtml() {
+      if (!inject) return [];
+      return [
+        {
+          tag: "script",
+          attrs: {
+            type: "module"
+          },
+          children: clientSource(endpoint, resolvedMode),
+          injectTo: "body"
+        }
+      ];
+    },
+    configureServer(server) {
+      server.middlewares.use(endpoint, async (req, res) => {
+        const file = path.resolve(root, commentsFile);
+        if (req.method === "GET") {
+          const annotations = await readAnnotations(file);
+          sendJson(res, { annotations });
+          return;
+        }
+        if (req.method === "POST") {
+          const body = await readBody(req);
+          const incoming = JSON.parse(body);
+          const annotations = await readAnnotations(file);
+          annotations.push(incoming);
+          await fs.mkdir(path.dirname(file), { recursive: true });
+          await fs.writeFile(file, JSON.stringify({ annotations }, null, 2));
+          sendJson(res, { ok: true, annotation: incoming });
+          return;
+        }
+        res.statusCode = 405;
+        res.end("Method Not Allowed");
+      });
+    },
+    resolveId(id) {
+      if (id === "/@markable/client") return id;
+    },
+    load(id) {
+      if (id !== "/@markable/client") return null;
+      return clientSource(endpoint, resolvedMode);
+    }
+  };
+}
+function resolveMode(mode, viteMode) {
+  if (mode === "review" || mode === "feedback") return mode;
+  return viteMode === "production" ? "feedback" : "review";
+}
+async function readAnnotations(file) {
+  try {
+    const raw = await fs.readFile(file, "utf8");
+    const parsed = JSON.parse(raw);
+    return parsed.annotations ?? [];
+  } catch {
+    return [];
+  }
+}
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    let body = "";
+    req.on("data", (chunk) => {
+      body += chunk;
+    });
+    req.on("end", () => resolve(body));
+    req.on("error", reject);
+  });
+}
+function sendJson(res, value) {
+  res.setHeader("Content-Type", "application/json; charset=utf-8");
+  res.end(JSON.stringify(value));
+}
+function clientSource(endpoint, mode) {
+  return `
+const endpoint = ${JSON.stringify(endpoint)};
+const mode = ${JSON.stringify(mode)};
+let candidateElement = null;
+let selectedElement = null;
+let selectedTarget = null;
+let dragging = false;
+let dragStart = null;
+let activeTab = "primary";
+const annotations = [];
+
+const labels = {
+  review: {
+    launcher: "\u30DE\u30FC\u30AF",
+    panelTitle: "\u3053\u306E\u30DA\u30FC\u30B8\u3092\u30DE\u30FC\u30AF",
+    tabPrimary: "\u30B3\u30E1\u30F3\u30C8",
+    tabSecondary: "AI\u306B\u4F9D\u983C",
+    placeholder: "\u30EC\u30D3\u30E5\u30FC\u30B3\u30E1\u30F3\u30C8\u3092\u5165\u529B",
+    submit: "\u30DE\u30FC\u30AF\u3092\u4FDD\u5B58",
+    helper: "\u30CF\u30A4\u30E9\u30A4\u30C8\u3055\u308C\u305F\u8981\u7D20\u3092\u30AF\u30EA\u30C3\u30AF\u3001\u7A7A\u767D\u3092\u30C9\u30E9\u30C3\u30B0\u3001\u307E\u305F\u306F\u30DA\u30FC\u30B8\u5168\u4F53\u306E\u30D5\u30A3\u30FC\u30C9\u30D0\u30C3\u30AF\u3092\u4FDD\u5B58\u3067\u304D\u307E\u3059\u3002",
+    empty: "\u307E\u3060\u30DE\u30FC\u30AF\u306F\u3042\u308A\u307E\u305B\u3093\u3002"
+  },
+  feedback: {
+    launcher: "\u30D5\u30A3\u30FC\u30C9\u30D0\u30C3\u30AF",
+    panelTitle: "\u30D5\u30A3\u30FC\u30C9\u30D0\u30C3\u30AF\u3092\u9001\u4FE1",
+    tabPrimary: "\u30D5\u30A3\u30FC\u30C9\u30D0\u30C3\u30AF",
+    tabSecondary: "\u8CEA\u554F",
+    placeholder: "\u3053\u306E\u30DA\u30FC\u30B8\u3078\u306E\u30D5\u30A3\u30FC\u30C9\u30D0\u30C3\u30AF\u3092\u5165\u529B",
+    submit: "\u9001\u4FE1",
+    helper: "\u30CF\u30A4\u30E9\u30A4\u30C8\u3055\u308C\u305F\u8981\u7D20\u3092\u30AF\u30EA\u30C3\u30AF\u3001\u7A7A\u767D\u3092\u30C9\u30E9\u30C3\u30B0\u3001\u307E\u305F\u306F\u30DA\u30FC\u30B8\u5168\u4F53\u306E\u30D5\u30A3\u30FC\u30C9\u30D0\u30C3\u30AF\u3092\u9001\u4FE1\u3067\u304D\u307E\u3059\u3002",
+    empty: "\u3053\u306E\u30BB\u30C3\u30B7\u30E7\u30F3\u3067\u306F\u307E\u3060\u30D5\u30A3\u30FC\u30C9\u30D0\u30C3\u30AF\u304C\u3042\u308A\u307E\u305B\u3093\u3002"
+  }
+}[mode];
+
+function applyBaseStyles(element) {
+  element.style.fontFamily = 'Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif';
+  element.style.fontSize = "14px";
+}
+
+function createLauncher() {
+  const launcher = document.createElement("button");
+  launcher.type = "button";
+  launcher.setAttribute("data-markable-launcher", "");
+  launcher.textContent = labels.launcher;
+  applyBaseStyles(launcher);
+  launcher.style.position = "fixed";
+  launcher.style.right = "20px";
+  launcher.style.bottom = "20px";
+  launcher.style.zIndex = "2147483647";
+  launcher.style.border = "0";
+  launcher.style.borderRadius = "999px";
+  launcher.style.padding = "12px 16px";
+  launcher.style.background = mode === "feedback" ? "#111827" : "#2563eb";
+  launcher.style.color = "#fff";
+  launcher.style.boxShadow = "0 14px 36px rgba(0, 0, 0, 0.24)";
+  launcher.style.cursor = "pointer";
+  return launcher;
+}
+
+function createPanel() {
+  const panel = document.createElement("form");
+  panel.setAttribute("data-markable-panel", "");
+  applyBaseStyles(panel);
+  panel.style.position = "fixed";
+  panel.style.right = "20px";
+  panel.style.bottom = "76px";
+  panel.style.zIndex = "2147483647";
+  panel.style.display = "none";
+  panel.style.background = "#fff";
+  panel.style.color = "#111827";
+  panel.style.border = "1px solid rgba(17, 24, 39, 0.14)";
+  panel.style.padding = "16px";
+  panel.style.borderRadius = "18px";
+  panel.style.boxShadow = "0 24px 70px rgba(15, 23, 42, 0.28)";
+  panel.style.width = "min(392px, calc(100vw - 32px))";
+  panel.innerHTML = '<div style="display:flex;align-items:center;justify-content:space-between;gap:12px;margin-bottom:12px"><strong data-markable-title data-markable-drag-handle style="font-size:16px;cursor:move;user-select:none">' + labels.panelTitle + '</strong><button type="button" data-markable-close aria-label="Close" style="border:0;background:transparent;font-size:20px;line-height:1;cursor:pointer;color:#6b7280">\xD7</button></div><div data-markable-tabs style="display:grid;grid-template-columns:1fr 1fr;padding:3px;border-radius:999px;background:#f3f4f6;margin-bottom:12px"><button type="button" data-markable-tab="primary" style="border:0;border-radius:999px;padding:8px;background:#fff;color:#111827;box-shadow:0 1px 3px rgba(0,0,0,.08);cursor:pointer">' + labels.tabPrimary + '</button><button type="button" data-markable-tab="secondary" style="border:0;border-radius:999px;padding:8px;background:transparent;color:#6b7280;cursor:pointer">' + labels.tabSecondary + '</button></div><p data-markable-target-summary style="margin:0 0 8px;color:#4b5563;font-size:12px">' + labels.helper + '</p><textarea name="message" required data-markable-input style="box-sizing:border-box;width:100%;min-height:104px;border:1px solid #d1d5db;border-radius:12px;padding:10px;resize:vertical"></textarea><div style="display:flex;justify-content:space-between;align-items:center;gap:8px;margin-top:10px"><button type="button" data-markable-cancel style="border:1px solid #d1d5db;background:#fff;border-radius:999px;padding:8px 12px;cursor:pointer">\u30AD\u30E3\u30F3\u30BB\u30EB</button><button type="submit" data-markable-submit style="border:0;background:#2563eb;color:#fff;border-radius:999px;padding:8px 14px;cursor:pointer">' + labels.submit + '</button></div><p data-markable-status role="status" style="min-height:16px;margin:8px 0 0;color:#4b5563;font-size:12px"></p>';
+  panel.querySelector("[data-markable-input]").placeholder = labels.placeholder;
+  return panel;
+}
+
+function createOverlay(kind) {
+  const overlay = document.createElement("div");
+  overlay.setAttribute(kind === "box" ? "data-markable-box" : "data-markable-highlight", "");
+  overlay.style.position = "fixed";
+  overlay.style.zIndex = "2147483646";
+  overlay.style.pointerEvents = "none";
+  overlay.style.border = kind === "box" ? "2px dashed #f59e0b" : "2px solid #2563eb";
+  overlay.style.background = kind === "box" ? "rgba(245,158,11,.12)" : "rgba(37,99,235,.08)";
+  overlay.style.borderRadius = "8px";
+  overlay.style.boxShadow = "0 0 0 4px rgba(37, 99, 235, 0.12)";
+  overlay.style.display = "none";
+  return overlay;
+}
+
+function createList() {
+  const list = document.createElement("aside");
+  list.setAttribute("data-markable-list", "");
+  applyBaseStyles(list);
+  list.style.position = "fixed";
+  list.style.left = "20px";
+  list.style.bottom = "20px";
+  list.style.zIndex = "2147483645";
+  list.style.width = "min(320px, calc(100vw - 40px))";
+  list.style.maxHeight = "40vh";
+  list.style.overflow = "auto";
+  list.style.display = "none";
+  list.style.border = "1px solid rgba(17,24,39,.14)";
+  list.style.borderRadius = "16px";
+  list.style.background = "rgba(255,255,255,.96)";
+  list.style.boxShadow = "0 18px 46px rgba(15,23,42,.18)";
+  list.style.padding = "10px";
+  return list;
+}
+
+function isMarkableElement(element) {
+  return Boolean(element?.closest?.("[data-markable-launcher], [data-markable-panel], [data-markable-highlight], [data-markable-box], [data-markable-list]"));
+}
+
+function selectorFor(element) {
+  if (element.id) return "#" + cssEscape(element.id);
+  const parts = [];
+  let current = element;
+  while (current && current.nodeType === Node.ELEMENT_NODE && current !== document.body) {
+    const tag = current.tagName.toLowerCase();
+    const parent = current.parentElement;
+    if (!parent) { parts.unshift(tag); break; }
+    const siblings = Array.from(parent.children).filter(child => child.tagName === current.tagName);
+    parts.unshift(siblings.length === 1 ? tag : tag + ":nth-of-type(" + (siblings.indexOf(current) + 1) + ")");
+    current = parent;
+  }
+  return parts.join(" > ");
+}
+function cssEscape(value) { return window.CSS?.escape ? window.CSS.escape(value) : value.replace(/[^a-zA-Z0-9_-]/g, "\\$&"); }
+function rectObject(rect) { return { x: rect.x, y: rect.y, width: rect.width, height: rect.height }; }
+
+function elementTarget(element) {
+  const rect = element.getBoundingClientRect();
+  return { kind: "dom_element", locator: { tag: element.tagName.toLowerCase(), selector: selectorFor(element), dataMarkableId: element.getAttribute("data-markable-id") || undefined, id: element.id || undefined, classes: element.classList.length ? Array.from(element.classList).slice(0, 8) : undefined, ariaLabel: element.getAttribute("aria-label") || undefined, role: element.getAttribute("role") || undefined, textSnippet: (element.innerText || element.textContent || "").trim().replace(/s+/g, " ").slice(0, 160) || undefined }, rect: rectObject(rect) };
+}
+function bboxTarget(rect) { return { kind: "bbox", locator: { url: location.href }, rect: rectObject(rect) }; }
+function currentPageTarget() { return { kind: "dom_range", locator: { url: location.href } }; }
+function currentTarget() { return selectedTarget || currentPageTarget(); }
+function context() { return { url: location.href, title: document.title, viewport: { width: innerWidth, height: innerHeight }, userAgent: navigator.userAgent, markableTab: activeTab }; }
+
+function positionOverlay(targetOverlay, rect) { targetOverlay.style.display = "block"; targetOverlay.style.left = rect.x + "px"; targetOverlay.style.top = rect.y + "px"; targetOverlay.style.width = rect.width + "px"; targetOverlay.style.height = rect.height + "px"; }
+function showOverlayFor(element) { positionOverlay(overlay, element.getBoundingClientRect()); }
+function hideOverlay(targetOverlay) { targetOverlay.style.display = "none"; }
+function isPanelOpen() { return panel.style.display !== "none"; }
+function practicalElementFor(element) {
+  if (!element || isMarkableElement(element)) return null;
+  const marked = element.closest("[data-markable-id]");
+  if (marked) return marked;
+  return element.closest("button, a, input, textarea, select, label, [role], [aria-label], li, article, section, form");
+}
+function targetAtPoint(clientX, clientY) {
+  const element = document.elementFromPoint(clientX, clientY);
+  return practicalElementFor(element);
+}
+function rectFromPoints(a, b) { const x = Math.min(a.x, b.x); const y = Math.min(a.y, b.y); return new DOMRect(x, y, Math.abs(a.x - b.x), Math.abs(a.y - b.y)); }
+
+function setTab(tab) {
+  activeTab = tab;
+  const input = panel.querySelector("[data-markable-input]");
+  input.placeholder = tab === "secondary" ? (mode === "feedback" ? "\u3053\u306E\u30DA\u30FC\u30B8\u306B\u3064\u3044\u3066\u8CEA\u554F\u3059\u308B" : "AI\u306B\u4F9D\u983C\u3057\u305F\u3044\u5909\u66F4\u5185\u5BB9\u3092\u5165\u529B") : labels.placeholder;
+  panel.querySelectorAll("[data-markable-tab]").forEach(button => {
+    const active = button.getAttribute("data-markable-tab") === tab;
+    button.style.background = active ? "#fff" : "transparent";
+    button.style.color = active ? "#111827" : "#6b7280";
+    button.style.boxShadow = active ? "0 1px 3px rgba(0,0,0,.08)" : "none";
+  });
+}
+function summarizeTarget(target) {
+  if (target?.kind === "dom_element") { const l = target.locator; return "\u5BFE\u8C61: " + (l.dataMarkableId || l.id || l.ariaLabel || l.selector || l.tag); }
+  if (target?.kind === "bbox") return "\u5BFE\u8C61: \u9078\u629E\u3057\u305F\u753B\u9762\u7BC4\u56F2";
+  return "\u5BFE\u8C61: \u73FE\u5728\u306E\u30DA\u30FC\u30B8";
+}
+function updateSelectedTarget(target) {
+  selectedTarget = target || null;
+  panel.querySelector("[data-markable-target-summary]").textContent = summarizeTarget(selectedTarget);
+}
+function updateSelectedElement(element) {
+  selectedElement = element || null;
+  if (selectedElement) showOverlayFor(selectedElement);
+}
+function openPanel(target) {
+  updateSelectedTarget(target);
+  panel.style.display = "block";
+  launcher.style.display = "none";
+  panel.querySelector("[data-markable-input]").focus();
+}
+function resetTargeting() { candidateElement = null; selectedElement = null; dragging = false; dragStart = null; selectedTarget = null; hideOverlay(overlay); hideOverlay(boxOverlay); }
+function closePanel() { panel.style.display = "none"; launcher.style.display = "block"; resetTargeting(); }
+function renderList() {
+  list.style.display = annotations.length ? "block" : "none";
+  list.innerHTML = '<strong data-markable-drag-handle style="display:block;margin-bottom:8px;cursor:move;user-select:none">\u6700\u8FD1\u306E' + (mode === "feedback" ? "\u30D5\u30A3\u30FC\u30C9\u30D0\u30C3\u30AF" : "\u30DE\u30FC\u30AF") + '</strong>' + (annotations.length ? annotations.slice(-4).reverse().map(item => '<article style="border-top:1px solid #e5e7eb;padding-top:8px;margin-top:8px"><div style="display:flex;align-items:flex-start;justify-content:space-between;gap:8px"><div style="min-width:0"><p style="margin:0 0 4px;color:#111827">' + escapeHtml(item.message).slice(0, 140) + '</p><small style="color:#6b7280">' + item.target.kind + ' \xB7 ' + new Date(item.createdAt).toLocaleTimeString() + '</small></div><button type="button" data-markable-copy-json="' + escapeHtml(item.id) + '" aria-label="\u30DE\u30FC\u30AFJSON\u3092\u30B3\u30D4\u30FC" title="JSON\u3092\u30B3\u30D4\u30FC" style="flex:0 0 auto;border:1px solid #d1d5db;background:#fff;color:#374151;border-radius:999px;padding:4px 8px;font-size:12px;line-height:1.2;cursor:pointer">JSON</button></div></article>').join('') : '<p style="margin:0;color:#6b7280">' + labels.empty + '</p>');
+}
+function escapeHtml(value) { return String(value).replace(/[&<>"]/g, char => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;'}[char])); }
+
+function makeDraggable(element, options = {}) {
+  let drag = null;
+  const handleSelector = options.handleSelector;
+  element.addEventListener("pointerdown", event => {
+    if (event.button !== 0) return;
+    if (handleSelector && !event.target.closest?.(handleSelector)) return;
+    if (!handleSelector && event.target.closest?.("button, input, textarea, select, a")) return;
+    const rect = element.getBoundingClientRect();
+    drag = { pointerId: event.pointerId, offsetX: event.clientX - rect.left, offsetY: event.clientY - rect.top, startX: event.clientX, startY: event.clientY, moved: false };
+    element.setPointerCapture?.(event.pointerId);
+    event.preventDefault();
+    event.stopPropagation();
+  });
+  element.addEventListener("pointermove", event => {
+    if (!drag || drag.pointerId !== event.pointerId) return;
+    const maxLeft = Math.max(0, innerWidth - element.offsetWidth);
+    const maxTop = Math.max(0, innerHeight - element.offsetHeight);
+    drag.moved = drag.moved || Math.abs(event.clientX - drag.startX) > 3 || Math.abs(event.clientY - drag.startY) > 3;
+    const left = Math.min(Math.max(0, event.clientX - drag.offsetX), maxLeft);
+    const top = Math.min(Math.max(0, event.clientY - drag.offsetY), maxTop);
+    element.style.left = left + "px";
+    element.style.top = top + "px";
+    element.style.right = "auto";
+    element.style.bottom = "auto";
+  });
+  element.addEventListener("pointerup", event => {
+    if (!drag || drag.pointerId !== event.pointerId) return;
+    element.releasePointerCapture?.(event.pointerId);
+    if (drag.moved) element.dataset.markableSuppressClickUntil = String(Date.now() + 250);
+    drag = null;
+  });
+  element.addEventListener("pointercancel", event => {
+    if (!drag || drag.pointerId !== event.pointerId) return;
+    element.releasePointerCapture?.(event.pointerId);
+    drag = null;
+  });
+}
+
+async function copyText(value) {
+  if (navigator.clipboard?.writeText) {
+    try {
+      await navigator.clipboard.writeText(value);
+      return true;
+    } catch {
+      // Fall back for embedded browsers that expose clipboard but reject writes.
+    }
+  }
+  const input = document.createElement("textarea");
+  input.value = value;
+  input.style.position = "fixed";
+  input.style.left = "-9999px";
+  document.body.append(input);
+  input.select();
+  const copied = document.execCommand("copy");
+  input.remove();
+  return copied;
+}
+
+const launcher = document.querySelector("[data-markable-launcher]") || createLauncher();
+const panel = document.querySelector("[data-markable-panel]") || createPanel();
+const overlay = document.querySelector("[data-markable-highlight]") || createOverlay("element");
+const boxOverlay = document.querySelector("[data-markable-box]") || createOverlay("box");
+const list = document.querySelector("[data-markable-list]") || createList();
+for (const node of [launcher, panel, overlay, boxOverlay, list]) if (!node.isConnected) document.body.append(node);
+makeDraggable(launcher);
+makeDraggable(panel, { handleSelector: "[data-markable-drag-handle]" });
+makeDraggable(list, { handleSelector: "[data-markable-drag-handle]" });
+setTab("primary"); renderList();
+
+launcher.addEventListener("click", () => {
+  if (Number(launcher.dataset.markableSuppressClickUntil || 0) > Date.now()) return;
+  openPanel(null);
+});
+panel.querySelector("[data-markable-close]").addEventListener("click", closePanel);
+panel.querySelector("[data-markable-cancel]").addEventListener("click", closePanel);
+panel.querySelectorAll("[data-markable-tab]").forEach(button => button.addEventListener("click", () => setTab(button.getAttribute("data-markable-tab"))));
+list.addEventListener("click", async event => {
+  const button = event.target.closest?.("[data-markable-copy-json]");
+  if (!button) return;
+  const annotation = annotations.find(item => item.id === button.getAttribute("data-markable-copy-json"));
+  if (!annotation) return;
+  try {
+    const copied = await copyText(JSON.stringify(annotation, null, 2));
+    button.textContent = copied ? "\u30B3\u30D4\u30FC\u6E08\u307F" : "\u30B3\u30D4\u30FC\u5931\u6557";
+  } catch {
+    button.textContent = "\u30B3\u30D4\u30FC\u5931\u6557";
+  }
+  setTimeout(() => { button.textContent = "JSON"; }, 1200);
+});
+
+document.addEventListener("pointermove", event => {
+  if (!isPanelOpen()) return;
+  if (dragging) { positionOverlay(boxOverlay, rectFromPoints(dragStart, { x: event.clientX, y: event.clientY })); return; }
+  const element = targetAtPoint(event.clientX, event.clientY);
+  if (!element) { candidateElement = null; if (!selectedElement) hideOverlay(overlay); return; }
+  candidateElement = element;
+  if (selectedElement) return;
+  showOverlayFor(element);
+}, true);
+document.addEventListener("click", event => {
+  if (!isPanelOpen()) return;
+  const element = targetAtPoint(event.clientX, event.clientY);
+  if (!element) return;
+  event.preventDefault();
+  event.stopPropagation();
+  updateSelectedElement(element);
+  updateSelectedTarget(elementTarget(element));
+}, true);
+document.addEventListener("pointerdown", event => {
+  if (!isPanelOpen() || isMarkableElement(event.target)) return;
+  const element = targetAtPoint(event.clientX, event.clientY);
+  if (element) return;
+  dragging = true;
+  dragStart = { x: event.clientX, y: event.clientY };
+  candidateElement = null;
+  updateSelectedElement(null);
+  hideOverlay(overlay);
+  positionOverlay(boxOverlay, new DOMRect(dragStart.x, dragStart.y, 0, 0));
+  event.preventDefault();
+}, true);
+document.addEventListener("pointerup", event => {
+  if (!dragging) return;
+  dragging = false;
+  const rect = rectFromPoints(dragStart, { x: event.clientX, y: event.clientY });
+  dragStart = null;
+  if (rect.width > 8 && rect.height > 8) {
+    updateSelectedTarget(bboxTarget(rect));
+  } else {
+    hideOverlay(boxOverlay);
+  }
+}, true);
+
+panel.addEventListener("submit", async event => {
+  event.preventDefault();
+  const message = String(new FormData(panel).get("message") || "").trim();
+  if (!message) return;
+  const now = new Date().toISOString();
+  const annotation = { id: "mark-" + Math.random().toString(36).slice(2, 10), mode, target: currentTarget(), message, status: "open", context: context(), createdAt: now, updatedAt: now };
+  const status = panel.querySelector("[data-markable-status]");
+  try {
+    const response = await fetch(endpoint, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(annotation) });
+    if (!response.ok) throw new Error("Request failed with " + response.status);
+    status.textContent = mode === "feedback" ? "\u3042\u308A\u304C\u3068\u3046\u3054\u3056\u3044\u307E\u3059\u3002\u30D5\u30A3\u30FC\u30C9\u30D0\u30C3\u30AF\u3092\u9001\u4FE1\u3057\u307E\u3057\u305F\u3002" : "\u30DE\u30FC\u30AF\u3092\u4FDD\u5B58\u3057\u307E\u3057\u305F\u3002";
+  } catch (error) {
+    console.warn("markable: unable to persist annotation", error, annotation);
+    status.textContent = "\u30ED\u30FC\u30AB\u30EB\u306B\u8A18\u9332\u3057\u307E\u3057\u305F\u3002\u6C38\u7D9A\u5316\u3059\u308B\u306B\u306F\u30A8\u30F3\u30C9\u30DD\u30A4\u30F3\u30C8\u3092\u8A2D\u5B9A\u3057\u3066\u304F\u3060\u3055\u3044\u3002";
+  }
+  annotations.push(annotation);
+  panel.reset();
+  renderList();
+  closePanel();
+});
+`;
+}
+export {
+  markable
+};

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@f12o/markable",
+  "version": "2026.6.0",
+  "description": "Headless interaction layer for marking artifacts with structured feedback and rewrite annotations.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/f4ah6o/markable.git"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./core": {
+      "types": "./dist/core.d.ts",
+      "import": "./dist/core.js"
+    },
+    "./dom": {
+      "types": "./dist/dom.d.ts",
+      "import": "./dist/dom.js"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "import": "./dist/vite.js"
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vite": "^6.0.3",
+    "vite-plus": "^0.1.24",
+    "vitest": "^4.1.9"
+  },
+  "peerDependencies": {
+    "vite": ">=5"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/core.ts src/dom.ts src/vite.ts --format esm --dts",
+    "typecheck": "tsc --noEmit",
+    "build:demo": "pnpm --filter @f12o/markable-vite-todo-demo build",
+    "build:shadcn-admin": "pnpm --filter @f12o/markable-shadcn-admin-demo build"
+  }
+}