@ampless/plugin-x-embed 1.0.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ampless contributors
+
+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,54 @@
+# @ampless/plugin-x-embed
+
+> English: [README.md](./README.md)
+
+ampless の投稿に x.com (Twitter) 埋め込みをインラインで表示するプラグイン。`https://x.com/<handle>/status/<id>` および `https://twitter.com/<handle>/status/<id>` 形式の URL を `<blockquote class="twitter-tweet">` として描画し、x の `widgets.js` がカード型の埋め込みに hydrate する。
+
+## インストール
+
+```sh
+npm i @ampless/plugin-x-embed
+```
+
+## 配線
+
+`cms.config.ts`:
+
+```ts
+import { defineConfig } from 'ampless'
+import xEmbedPlugin from '@ampless/plugin-x-embed'
+
+export default defineConfig({
+  plugins: [xEmbedPlugin()],
+})
+```
+
+tiptap エディタ側は `templates/_shared/app/(admin)/admin/_editor-bootstrap.tsx` で Node を登録する:
+
+```tsx
+'use client'
+import { installAdminEditorExtensions } from '@ampless/admin/editor'
+import { tweetEditor } from '@ampless/plugin-x-embed/editor'
+
+export function EditorBootstrap({ children }: { children: React.ReactNode }) {
+  installAdminEditorExtensions([tweetEditor.extension])
+  return <>{children}</>
+}
+```
+
+その上で `createAdminLayout(admin, { editorBootstrap: EditorBootstrap })` に渡す。
+
+## ページレベルスクリプト (widgets.js)
+
+本プラグインは `publicPostScript` capability を宣言している。`{await ampless.publicPostScriptsForPage([post])}` を呼んでいるテーマ（Phase 7 以降の first-party テーマはすべて該当）は、ページ上の投稿のいずれかに tweet 埋め込みが含まれる場合に `platform.twitter.com/widgets.js` を 1 回だけ出力する。
+
+## CSP
+
+ページレベルスクリプトは `platform.twitter.com/widgets.js` を読み込み、これが `<blockquote>` 要素を `platform.twitter.com` を src とする iframe に置き換える。サイト側 CSP には以下が必要:
+
+- `script-src https://platform.twitter.com`
+- `frame-src https://platform.twitter.com`
+
+## License
+
+MIT

package/README.md

@@ -0,0 +1,54 @@
+# @ampless/plugin-x-embed
+
+> 日本語版: [README.ja.md](./README.ja.md)
+
+Inline x.com (Twitter) embeds for ampless posts. Renders `https://x.com/<handle>/status/<id>` and `https://twitter.com/<handle>/status/<id>` URLs as `<blockquote class="twitter-tweet">` elements that x's `widgets.js` hydrates into the rich embed card.
+
+## Install
+
+```sh
+npm i @ampless/plugin-x-embed
+```
+
+## Wire up
+
+`cms.config.ts`:
+
+```ts
+import { defineConfig } from 'ampless'
+import xEmbedPlugin from '@ampless/plugin-x-embed'
+
+export default defineConfig({
+  plugins: [xEmbedPlugin()],
+})
+```
+
+For the tiptap editor side, register the Node in `templates/_shared/app/(admin)/admin/_editor-bootstrap.tsx`:
+
+```tsx
+'use client'
+import { installAdminEditorExtensions } from '@ampless/admin/editor'
+import { tweetEditor } from '@ampless/plugin-x-embed/editor'
+
+export function EditorBootstrap({ children }: { children: React.ReactNode }) {
+  installAdminEditorExtensions([tweetEditor.extension])
+  return <>{children}</>
+}
+```
+
+Then thread it into `createAdminLayout(admin, { editorBootstrap: EditorBootstrap })`.
+
+## Page-level script (widgets.js)
+
+The plugin declares the `publicPostScript` capability. Themes that already call `{await ampless.publicPostScriptsForPage([post])}` (the first-party themes all do as of Phase 7) automatically pick up `platform.twitter.com/widgets.js` — emitted once per page when any post on that page contains a tweet.
+
+## CSP
+
+The page-level script loads `platform.twitter.com/widgets.js`, which in turn hydrates `<blockquote>` elements into iframes pointing at `platform.twitter.com`. Your site's CSP needs:
+
+- `script-src https://platform.twitter.com`
+- `frame-src https://platform.twitter.com`
+
+## License
+
+MIT

package/dist/chunk-6SPJOY2C.js

@@ -0,0 +1,53 @@
+// src/shared.tsx
+import { jsx } from "react/jsx-runtime";
+var TWEET_URL = /^https:\/\/(?:x\.com|twitter\.com)\/[A-Za-z0-9_]{1,15}\/status\/(\d{1,25})(?:[?&#]\S*)?$/;
+var TWEET_ID = /^\d{1,25}$/;
+function TweetEmbed({ tweetId }) {
+  if (typeof tweetId !== "string" || !TWEET_ID.test(tweetId)) return null;
+  return /* @__PURE__ */ jsx("blockquote", { className: "twitter-tweet", "data-dnt": "true", children: /* @__PURE__ */ jsx("a", { href: `https://twitter.com/i/status/${tweetId}` }) });
+}
+function parseTweetUrl(url) {
+  const trimmed = url.trim();
+  const m = trimmed.match(TWEET_URL);
+  if (!m) return null;
+  return m[1] ?? null;
+}
+function hasTweetIn(post) {
+  if (post.format === "tiptap") {
+    return hasTweetNodeInTiptap(post.body);
+  }
+  if (post.format === "markdown") {
+    if (typeof post.body !== "string") return false;
+    return hasTweetUrlInMarkdown(post.body);
+  }
+  if (post.format === "html") {
+    if (typeof post.body !== "string") return false;
+    return post.body.includes("twitter-tweet");
+  }
+  return false;
+}
+function hasTweetNodeInTiptap(body) {
+  if (typeof body === "string") return body.includes("twitter-tweet");
+  if (!body || typeof body !== "object") return false;
+  const node = body;
+  if (node.type === "amplessTweet") return true;
+  if (Array.isArray(node.content)) {
+    for (const child of node.content) {
+      if (hasTweetNodeInTiptap(child)) return true;
+    }
+  }
+  return false;
+}
+function hasTweetUrlInMarkdown(md) {
+  for (const line of md.split(/\r?\n/)) {
+    if (TWEET_URL.test(line.trim())) return true;
+  }
+  return false;
+}
+
+export {
+  TWEET_URL,
+  TweetEmbed,
+  parseTweetUrl,
+  hasTweetIn
+};

package/dist/editor.d.ts

@@ -0,0 +1,27 @@
+import { Node } from '@tiptap/core';
+
+declare module '@tiptap/core' {
+    interface Commands<ReturnType> {
+        amplessTweet: {
+            /** Insert a tweet embed node with the given tweet id. */
+            setTweet: (opts: {
+                tweetId: string;
+            }) => ReturnType;
+            /**
+             * Insert a tweet embed from a URL. Returns false (and does
+             * nothing) if the URL doesn't match the canonical x.com /
+             * twitter.com /status/ form.
+             */
+            insertTweetFromUrl: (url: string) => ReturnType;
+        };
+    }
+}
+declare const AmplessTweetNode: Node<any, any>;
+/**
+ * Named export consumed by templates' `_editor-bootstrap.tsx`.
+ */
+declare const tweetEditor: {
+    extension: Node<any, any>;
+};
+
+export { AmplessTweetNode, tweetEditor };

package/dist/editor.js

@@ -0,0 +1,83 @@
+"use client";
+import {
+  TWEET_URL,
+  parseTweetUrl
+} from "./chunk-6SPJOY2C.js";
+
+// src/editor.tsx
+import { Node, mergeAttributes } from "@tiptap/core";
+var AmplessTweetNode = Node.create({
+  name: "amplessTweet",
+  group: "block",
+  atom: true,
+  selectable: true,
+  draggable: true,
+  addAttributes() {
+    return {
+      tweetId: {
+        default: "",
+        parseHTML: (el) => el.getAttribute("data-tweet-id") ?? "",
+        renderHTML: (attrs) => ({
+          "data-tweet-id": String(attrs.tweetId ?? "")
+        })
+      }
+    };
+  },
+  parseHTML() {
+    return [
+      {
+        tag: "div[data-ampless-tweet]"
+      }
+    ];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return [
+      "div",
+      mergeAttributes(HTMLAttributes, {
+        "data-ampless-tweet": "",
+        class: "ampless-tweet-placeholder"
+      }),
+      ["span", {}, `Tweet: ${HTMLAttributes["data-tweet-id"] ?? ""}`]
+    ];
+  },
+  addCommands() {
+    return {
+      setTweet: (opts) => ({ commands }) => commands.insertContent({
+        type: this.name,
+        attrs: { tweetId: opts.tweetId }
+      }),
+      insertTweetFromUrl: (url) => ({ commands }) => {
+        const tweetId = parseTweetUrl(url);
+        if (!tweetId) return false;
+        return commands.insertContent({
+          type: this.name,
+          attrs: { tweetId }
+        });
+      }
+    };
+  },
+  addPasteRules() {
+    return [
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      {
+        find: TWEET_URL,
+        handler: ({ range, match, commands }) => {
+          const tweetId = match[1];
+          if (!tweetId) return;
+          commands.deleteRange(range);
+          commands.insertContent({
+            type: this.name,
+            attrs: { tweetId }
+          });
+        }
+      }
+    ];
+  }
+});
+var tweetEditor = {
+  extension: AmplessTweetNode
+};
+export {
+  AmplessTweetNode,
+  tweetEditor
+};

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+import { AmplessPlugin } from 'ampless';
+import { ReactElement } from 'react';
+
+/**
+ * Tweet URL pattern. Accepts both `x.com` and `twitter.com` hosts, any
+ * valid handle (1-15 chars, [A-Za-z0-9_]), and a numeric status id
+ * (1-25 digits — far above any actual real tweet id but safely capped
+ * to prevent overflow / abuse). Anchored with `^...$` so the markdown
+ * walker only intercepts single-URL paragraphs.
+ *
+ * Captures:
+ *   - Group 1: tweet status id
+ */
+declare const TWEET_URL: RegExp;
+interface TweetEmbedProps {
+    tweetId: string;
+}
+/**
+ * Render a tweet as a `<blockquote class="twitter-tweet">` with a link
+ * to the canonical twitter.com URL. Widgets.js (injected via the
+ * plugin's `publicPostScript`) finds blockquotes with this class on
+ * page load and replaces them with the rich embed card.
+ *
+ * Defensive: an invalid `tweetId` (not matching the numeric pattern)
+ * renders nothing.
+ */
+declare function TweetEmbed({ tweetId }: TweetEmbedProps): ReactElement | null;
+/**
+ * Extract the tweet id from a URL string. Returns `null` if the URL
+ * doesn't match the canonical x.com / twitter.com status form. Used
+ * by the tiptap editor's paste rule + the `contentFields` markdown
+ * walker + `hasTweetIn`.
+ */
+declare function parseTweetUrl(url: string): string | null;
+/**
+ * Scan a post body for any tweet embed. Used by the plugin's
+ * `publicPostScript` to decide whether widgets.js is actually needed
+ * for a given page — pages with no tweets don't pay for the script
+ * round trip.
+ */
+declare function hasTweetIn(post: {
+    format?: string;
+    body?: unknown;
+}): boolean;
+
+interface XEmbedPluginOptions {
+    /**
+     * Override the plugin's `name` (and admin-side namespace). Multi-
+     * instance is not currently supported by the contentFields registry.
+     */
+    name?: string;
+}
+declare function xEmbedPlugin(opts?: XEmbedPluginOptions): AmplessPlugin;
+
+export { TWEET_URL, TweetEmbed, type XEmbedPluginOptions, xEmbedPlugin as default, hasTweetIn, parseTweetUrl };

package/dist/index.js

@@ -0,0 +1,55 @@
+import {
+  TWEET_URL,
+  TweetEmbed,
+  hasTweetIn,
+  parseTweetUrl
+} from "./chunk-6SPJOY2C.js";
+
+// src/index.tsx
+import { definePlugin } from "ampless";
+import { jsx } from "react/jsx-runtime";
+function xEmbedPlugin(opts = {}) {
+  return definePlugin({
+    name: opts.name ?? "@ampless/plugin-x-embed",
+    apiVersion: 1,
+    packageName: "@ampless/plugin-x-embed",
+    trust_level: "trusted",
+    capabilities: ["contentFields", "publicPostScript"],
+    displayName: { en: "x.com (Twitter) embeds", ja: "x.com (Twitter) \u57CB\u3081\u8FBC\u307F" },
+    contentFields: [
+      {
+        kind: "tiptap",
+        nodeType: "amplessTweet",
+        render: (node) => {
+          const tweetId = String(node.attrs?.tweetId ?? "");
+          return /* @__PURE__ */ jsx(TweetEmbed, { tweetId });
+        }
+      },
+      {
+        kind: "markdown-url",
+        pattern: TWEET_URL,
+        render: ({ match }) => {
+          const tweetId = match[1] ?? "";
+          return /* @__PURE__ */ jsx(TweetEmbed, { tweetId });
+        }
+      }
+    ],
+    publicPostScript(post) {
+      if (!hasTweetIn(post)) return [];
+      return [
+        {
+          id: "amplessTweet:widgets",
+          src: "https://platform.twitter.com/widgets.js",
+          async: true
+        }
+      ];
+    }
+  });
+}
+export {
+  TWEET_URL,
+  TweetEmbed,
+  xEmbedPlugin as default,
+  hasTweetIn,
+  parseTweetUrl
+};

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@ampless/plugin-x-embed",
+  "version": "1.0.0-alpha.1",
+  "description": "x.com (Twitter) embed plugin for ampless — renders tweet URLs inline as blockquotes hydrated by widgets.js",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./editor": {
+      "import": "./dist/editor.js",
+      "types": "./dist/editor.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/heavymoons/ampless.git",
+    "directory": "packages/plugin-x-embed"
+  },
+  "homepage": "https://github.com/heavymoons/ampless/tree/main/packages/plugin-x-embed#readme",
+  "bugs": "https://github.com/heavymoons/ampless/issues",
+  "peerDependencies": {
+    "@tiptap/core": "^3",
+    "react": "^18 || ^19",
+    "ampless": "1.0.0-alpha.42"
+  },
+  "devDependencies": {
+    "@tiptap/core": "^3.23.6",
+    "@types/react": "^19.2.15",
+    "@types/react-dom": "^19.2.3",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6"
+  },
+  "keywords": [
+    "ampless",
+    "plugin",
+    "ampless-plugin",
+    "twitter",
+    "x.com",
+    "embed",
+    "cms"
+  ],
+  "amplessPlugin": {
+    "apiVersion": 1,
+    "name": "@ampless/plugin-x-embed",
+    "trustLevel": "trusted",
+    "capabilities": [
+      "contentFields",
+      "publicPostScript"
+    ],
+    "displayName": {
+      "en": "x.com (Twitter) embeds",
+      "ja": "x.com (Twitter) 埋め込み"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  }
+}