@traq-markdown-engine/traq-plugin 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2020 traP
+Copyright (c) 2026 東京工業大学デジタル創作同好会traP
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,41 @@
+# traq-plugin: traP Markdown extensions
+
+traP 固有の Markdown 拡張部品を提供します。traQ 向けの組み合わせと配布は
+[SDK](../../sdk/README.md) が所有します。
+
+| crate                      | 責務                                      |
+| -------------------------- | ----------------------------------------- |
+| `markdown-trap-contracts`  | スタンプ、参照、spoiler、空行のノード契約 |
+| `markdown-trap-syntax`     | traP 拡張の構文解析                       |
+| `markdown-trap-text`       | traP ノードのテキスト描画                 |
+| `markdown-trap-extraction` | 参照などの抽出                            |
+
+各ルールの Plugin を、利用側の GrammarBuilder / PresetBuilder に追加して使います。
+文法の選択と順序、通知 URL の表示方針、処理結果の組み合わせは利用側で決めます。
+[SDK の構成・実行例](../../sdk/crates/processing)
+を参照してください。
+
+## 開発
+
+共通の環境準備と検証は [ルートの CONTRIBUTING](../../../CONTRIBUTING.md) に従います。依存する
+[core](../../core/README.md) と
+[commonmark-plugin](../commonmark/README.md) は同じ workspace のローカルパスから参照します。SDK の構成・配布には依存しません。
+
+## TypeScript / HTML rendering
+
+TypeScript の実装もこのリポジトリの責務に合わせて配置しています。
+
+| TypeScript package                        | 責務                                                                   |
+| ----------------------------------------- | ---------------------------------------------------------------------- |
+| `@traq-markdown-engine/core`              | 共通 AST 型、HTML handler・Plugin・PresetBuilder、契約検証と生成の基盤 |
+| `@traq-markdown-engine/commonmark-plugin` | CommonMark・汎用拡張の生成ノード型と HTML 描画                         |
+| `@traq-markdown-engine/traq-plugin`       | traP の生成ノード型・参照・スタンプ等の HTML 描画                      |
+| `@traq-markdown-engine/sdk`               | Wasm / Go / TypeScript 配布、traQ の描画構成・preview・CSS             |
+
+AST の共通形は core の `typescript/ast.ts` に一度だけ定義し、SDK の生成 bindings はそれを構文の union で特殊化します。構文の payload は Rust を正として生成し、commonmark-plugin と traq-plugin の `bun run generate:bindings` でそれぞれの契約 crate から再生成できます。
+
+HTML API は `/renderer` サブパスです。traQ は `@traq-markdown-engine/sdk/renderer` の `messageRenderers`、CSS は `@traq-markdown-engine/sdk/index.css` を利用します。
+
+## Go contracts
+
+The Go module is `github.com/uni-kakurenbo/traq-markdown-engine/packages/plugins/traq/go`. Payloads and node factories are generated from this repository's Rust contracts by `bun run generate:bindings`. The canonical tree and Wasm runtime belong to the core Go module.

package/dist/generated/trap.d.ts

@@ -0,0 +1,49 @@
+export type BlankLineData = Record<symbol, never>;
+export type EmbeddingData = {
+    type: EmbeddingKind;
+    id: string;
+    label: string;
+    /**
+     * Original JSON notation, available to renderers that display it as text.
+     */
+    literal: string;
+};
+export type EmbeddingKind = 'file' | 'message';
+export type ReferenceData = {
+    type: ReferenceKind;
+    id: string;
+    label: string;
+};
+export type ReferenceKind = 'user' | 'group' | 'channel';
+export type SpoilerData = Record<symbol, never>;
+export type StampData = {
+    literal: string;
+};
+export type NodeKind = {
+    kind: 'markdown_trap_contracts::compat::BlankLineData';
+    data: BlankLineData;
+} | {
+    kind: 'markdown_trap_contracts::embedding::EmbeddingData';
+    data: EmbeddingData;
+} | {
+    kind: 'markdown_trap_contracts::reference::ReferenceData';
+    data: ReferenceData;
+} | {
+    kind: 'markdown_trap_contracts::spoiler::SpoilerData';
+    data: SpoilerData;
+} | {
+    kind: 'markdown_trap_contracts::stamp::StampData';
+    data: StampData;
+};
+export declare const names: Readonly<{
+    readonly BlankLine: 'markdown_trap_contracts::compat::BlankLineData';
+    readonly Embedding: 'markdown_trap_contracts::embedding::EmbeddingData';
+    readonly Reference: 'markdown_trap_contracts::reference::ReferenceData';
+    readonly Spoiler: 'markdown_trap_contracts::spoiler::SpoilerData';
+    readonly Stamp: 'markdown_trap_contracts::stamp::StampData';
+}>;
+export declare const nodes: ReadonlyMap<string, (data: unknown) => boolean>;
+export declare function isKnownNode<T extends {
+    kind: string;
+    data: unknown;
+}>(node: T): node is T & NodeKind;

package/dist/generated/trap.js

@@ -0,0 +1,41 @@
+// Generated from Rust node payload types. Do not edit.
+import { fields, oneOf, string } from '@traq-markdown-engine/core/validation';
+export const names = Object.freeze({
+    BlankLine: 'markdown_trap_contracts::compat::BlankLineData',
+    Embedding: 'markdown_trap_contracts::embedding::EmbeddingData',
+    Reference: 'markdown_trap_contracts::reference::ReferenceData',
+    Spoiler: 'markdown_trap_contracts::spoiler::SpoilerData',
+    Stamp: 'markdown_trap_contracts::stamp::StampData'
+});
+const validators = new Map([
+    [
+        'markdown_trap_contracts::compat::BlankLineData',
+        value => fields(value, {}, {})
+    ],
+    [
+        'markdown_trap_contracts::embedding::EmbeddingData',
+        value => fields(value, {
+            id: string,
+            label: string,
+            literal: string,
+            type: oneOf('file', 'message')
+        }, {})
+    ],
+    [
+        'markdown_trap_contracts::reference::ReferenceData',
+        value => fields(value, { id: string, label: string, type: oneOf('user', 'group', 'channel') }, {})
+    ],
+    [
+        'markdown_trap_contracts::spoiler::SpoilerData',
+        value => fields(value, {}, {})
+    ],
+    [
+        'markdown_trap_contracts::stamp::StampData',
+        value => fields(value, { literal: string }, {})
+    ]
+]);
+export const nodes = new Map(validators);
+// Check this payload only; children can still contain unknown nodes.
+export function isKnownNode(node) {
+    return validators.get(node.kind)?.(node.data) ?? false;
+}

package/dist/renderer/index.d.ts

@@ -0,0 +1,4 @@
+import { Plugin } from '@traq-markdown-engine/core/renderer';
+import type { Options } from './types.js';
+export type { Options, Store } from './types.js';
+export declare function plugin({ store, baseUrl, validateLink }?: Options): Plugin;

package/dist/renderer/index.js

@@ -0,0 +1,18 @@
+import { validateLink as defaultPolicy } from '@traq-markdown-engine/commonmark-plugin/policy';
+import { Plugin as Declaration } from '@traq-markdown-engine/core/definitions';
+import { checked, escapeHtml } from '@traq-markdown-engine/core/html';
+import { Plugin } from '@traq-markdown-engine/core/renderer';
+import { isKnownNode, names } from '@traq-markdown-engine/traq-plugin/nodes';
+import { renderReference } from './reference.js';
+import { stampRenderer } from './stamp.js';
+const declaration = Declaration.group('trap').new('presentation');
+export function plugin({ store, baseUrl, validateLink = defaultPolicy } = {}) {
+    const result = new Plugin(declaration);
+    result.on(names.Reference, checked(names.Reference, isKnownNode, node => renderReference(node, store, validateLink)));
+    result.on(names.Spoiler, checked(names.Spoiler, isKnownNode, (n, ctx) => '<span class="spoiler">' + ctx.render(n.children) + '</span>'));
+    result.on(names.BlankLine, checked(names.BlankLine, isKnownNode, () => '<br>\n'));
+    result.on(names.Embedding, checked(names.Embedding, isKnownNode, node => escapeHtml(node.data.literal)));
+    const stamp = stampRenderer({ store, baseUrl });
+    result.on(names.Stamp, checked(names.Stamp, isKnownNode, node => stamp(node.data.literal)));
+    return result;
+}

package/dist/renderer/reference.d.ts

@@ -0,0 +1,6 @@
+import type { Node } from '@traq-markdown-engine/core/renderer';
+import type { ReferenceData } from '@traq-markdown-engine/traq-plugin/nodes';
+import type { Options } from './types.js';
+export declare function renderReference(node: Node & {
+    data: ReferenceData;
+}, store: Options['store'], validateLink: (destination: string) => boolean): string;

package/dist/renderer/reference.js

@@ -0,0 +1,27 @@
+import { attributes, escapeHtml } from '@traq-markdown-engine/core/html';
+export function renderReference(node, store, validateLink) {
+    const { type, id, label } = node.data;
+    if (!store)
+        return escapeHtml(label);
+    const me = store.getMe?.();
+    const href = type === 'user'
+        ? store.generateUserHref?.(id)
+        : type === 'group'
+            ? store.generateUserGroupHref?.(id)
+            : store.generateChannelHref?.(id);
+    if (!href || !validateLink(href))
+        return escapeHtml(label);
+    const highlight = type === 'user'
+        ? id === me?.id
+        : type === 'group' &&
+            (store.getUserGroup?.(id)?.members?.some(u => u.id === me?.id) ?? false);
+    const cls = `message-${type}-link`;
+    return ('<a' +
+        attributes([
+            ['href', href],
+            ['class', highlight ? `${cls}-highlight ${cls}` : cls]
+        ]) +
+        '>' +
+        escapeHtml(label) +
+        '</a>');
+}

package/dist/renderer/stamp-effects.d.ts

@@ -0,0 +1,4 @@
+export declare const animeEffects: readonly ['rotate', 'rotate-inv', 'wiggle', 'parrot', 'zoom', 'inversion', 'turn', 'turn-v', 'happa', 'pyon', 'flashy', 'pull', 'atsumori', 'stretch', 'stretch-v', 'conga', 'conga-inv', 'marquee', 'marquee-inv', 'rainbow', 'ascension', 'shake', 'party', 'attract'];
+export declare const sizeEffects: readonly ['ex-large', 'large', 'small'];
+export type AnimeEffect = (typeof animeEffects)[number];
+export type SizeEffect = (typeof sizeEffects)[number];

package/dist/renderer/stamp-effects.js

@@ -0,0 +1,27 @@
+export const animeEffects = [
+    'rotate',
+    'rotate-inv',
+    'wiggle',
+    'parrot',
+    'zoom',
+    'inversion',
+    'turn',
+    'turn-v',
+    'happa',
+    'pyon',
+    'flashy',
+    'pull',
+    'atsumori',
+    'stretch',
+    'stretch-v',
+    'conga',
+    'conga-inv',
+    'marquee',
+    'marquee-inv',
+    'rainbow',
+    'ascension',
+    'shake',
+    'party',
+    'attract'
+];
+export const sizeEffects = ['ex-large', 'large', 'small'];

package/dist/renderer/stamp.d.ts

@@ -0,0 +1,2 @@
+import type { Options } from './types.js';
+export declare function stampRenderer({ store, baseUrl }?: Options): (raw: string) => string;

package/dist/renderer/stamp.js

@@ -0,0 +1,106 @@
+import { validateLink } from '@traq-markdown-engine/commonmark-plugin/policy';
+import { escapeHtml } from '@traq-markdown-engine/core/html';
+import { animeEffects, sizeEffects } from './stamp-effects.js';
+const animeEffectSet = new Set(animeEffects);
+const sizeEffectSet = new Set(sizeEffects);
+const animeEffectAliasMap = new Map([
+    ['marquee', 'conga'],
+    ['marquee-inv', 'conga-inv']
+]);
+const maxEffectCount = 5;
+const wrapWithEffect = (stampHtml, animeEffects, sizeEffect) => {
+    const filterOpenTag = animeEffects
+        .map((e, i) => `<span class="emoji-effect ${e}${i === 0 && sizeEffect ? ` ${sizeEffect}` : ''}">`)
+        .join('');
+    const filterCloseTag = '</span>'.repeat(animeEffects.length);
+    return filterOpenTag + stampHtml + filterCloseTag;
+};
+const isSizeEffect = (e) => sizeEffectSet.has(e);
+const isAnimeEffect = (e) => animeEffectSet.has(e);
+const renderStampDomWithStyle = (rawMatch, stampName, imgTitle, style, effects) => {
+    const escapedTitle = escapeHtml(imgTitle);
+    const escapedStyle = escapeHtml(style);
+    const escapedName = escapeHtml(stampName);
+    const sizeEffects = effects.filter(isSizeEffect);
+    const animeEffects = effects.filter(isAnimeEffect);
+    // 知らないエフェクトはダメ
+    if (sizeEffects.length + animeEffects.length < effects.length) {
+        return escapeHtml(rawMatch);
+    }
+    // アニメーション系エフェクトは5つまで
+    if (animeEffects.length > maxEffectCount) {
+        return escapeHtml(rawMatch);
+    }
+    // aliasの置き換え
+    const replacedAnimeEffects = animeEffects.map(e => animeEffectAliasMap.get(e) ?? e);
+    // 複数サイズ指定が合った場合は最後のものを適用
+    const sizeEffectClass = sizeEffects[sizeEffects.length - 1] || '';
+    const stampHtml = `<i class="emoji message-emoji ${sizeEffectClass}" title=":${escapedTitle}:" style="${escapedStyle};">:${escapedName}:</i>`;
+    return wrapWithEffect(stampHtml, replacedAnimeEffects, sizeEffectClass);
+};
+const renderStampDom = (rawMatch, stampName, imgTitle, imgUrl, effects) => {
+    if (!validateLink(imgUrl) || /^(?:mailto|ftp):/i.test(imgUrl)) {
+        return escapeHtml(rawMatch);
+    }
+    const safeUrl = imgUrl.replace(/[\s"'()\\]/g, c => '%' + c.charCodeAt(0).toString(16).toUpperCase());
+    return renderStampDomWithStyle(rawMatch, stampName, imgTitle, 'background-image: url(' + safeUrl + ')', effects);
+};
+const stampReg = /^[a-zA-Z0-9+_-]{1,32}$/;
+const hslReg = /(?<color>hsl\(\d+,\s*[\d]+(?:\.[\d]+)?%,\s*[\d]+(?:\.[\d]+)?%\))(?<effects>.*)/;
+const hexReg = /0x(?<color>[0-9a-fA-F]{6})(?<effects>.*)/;
+const renderHslStamp = (match) => {
+    // HSL: hsl(..., ...%, ...%)
+    const { color = '', effects = '' } = match.groups ?? {};
+    return renderStampDomWithStyle(`:${match[0]}:`, color, color, `background-color: ${color}`, effects === '' ? [] : effects.split('.').slice(1));
+};
+const renderHexStamp = (match) => {
+    // Hex: 0x......
+    const { color = '', effects = '' } = match.groups ?? {};
+    return renderStampDomWithStyle(`:${match[0]}:`, `0x${color}`, `0x${color}`, `background-color: #${color}`, effects === '' ? [] : effects.split('.').slice(1));
+};
+export function stampRenderer({ store, baseUrl = '' } = {}) {
+    const getStampImageUrl = (fileId) => {
+        if (store?.generateStampHref) {
+            return store.generateStampHref(fileId);
+        }
+        return `${baseUrl}/api/v3/files/${encodeURIComponent(fileId)}`;
+    };
+    const renderUserStamp = (stampName, raw, effects) => {
+        // 先頭の@を除いたものがユーザー名
+        const userName = stampName.slice(1);
+        const user = store?.getUserByName?.(userName);
+        if (!user) {
+            return escapeHtml(raw);
+        }
+        return renderStampDom(raw, stampName, stampName, getStampImageUrl(user.iconFileId), effects);
+    };
+    const renderNormalStamp = (stampName, raw, effects) => {
+        const stamp = store?.getStampByName?.(stampName);
+        if (!stamp) {
+            return escapeHtml(raw);
+        }
+        return renderStampDom(raw, stampName, stamp.name, getStampImageUrl(stamp.fileId), effects);
+    };
+    const renderStamp = (raw) => {
+        const inner = raw.slice(1, -1);
+        const hexMatch = hexReg.exec(inner);
+        if (hexMatch) {
+            return renderHexStamp(hexMatch);
+        }
+        const hslMatch = hslReg.exec(inner);
+        if (hslMatch) {
+            return renderHslStamp(hslMatch);
+        }
+        const [stampName, ...effects] = inner.split('.');
+        // ユーザーアイコン
+        if (stampName.startsWith('@')) {
+            return renderUserStamp(stampName, raw, effects);
+        }
+        if (!stampReg.exec(stampName)) {
+            return escapeHtml(raw);
+        }
+        // 通常スタンプ
+        return renderNormalStamp(stampName, raw, effects);
+    };
+    return renderStamp;
+}

package/dist/renderer/types.d.ts

@@ -0,0 +1,26 @@
+export interface Store {
+    getMe?(): Readonly<{
+        id: string;
+    }> | undefined;
+    getUserGroup?(id: string): Readonly<{
+        members: readonly Readonly<{
+            id: string;
+        }>[];
+    }> | undefined;
+    getStampByName?(name: string): Readonly<{
+        name: string;
+        fileId: string;
+    }> | undefined;
+    getUserByName?(name: string): Readonly<{
+        iconFileId: string;
+    }> | undefined;
+    generateUserHref?(id: string): string;
+    generateUserGroupHref?(id: string): string;
+    generateChannelHref?(id: string): string;
+    generateStampHref?(fileId: string): string;
+}
+export interface Options {
+    store?: Readonly<Store>;
+    baseUrl?: string;
+    validateLink?(destination: string): boolean;
+}

package/dist/renderer/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@traq-markdown-engine/traq-plugin",
+  "version": "0.1.0",
+  "description": "traQ-specific Markdown contracts and HTML rendering.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/uni-kakurenbo/traq-markdown-engine.git",
+    "directory": "packages/plugins/traq"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    "./nodes": {
+      "types": "./dist/generated/trap.d.ts",
+      "import": "./dist/generated/trap.js"
+    },
+    "./renderer": {
+      "types": "./dist/renderer/index.d.ts",
+      "import": "./dist/renderer/index.js"
+    },
+    "./stamp-effects": {
+      "types": "./dist/renderer/stamp-effects.d.ts",
+      "import": "./dist/renderer/stamp-effects.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "bun run ../../../scripts/tsc.ts -p typescript/tsconfig.build.json",
+    "generate:bindings": "bun run ../../../scripts/generate-bindings.ts traq-plugin",
+    "typecheck": "bun run ../../../scripts/tsc.ts -p typescript/tsconfig.json"
+  },
+  "devDependencies": {
+    "@traq-markdown-engine/commonmark-plugin": "workspace:*",
+    "@traq-markdown-engine/core": "workspace:*"
+  },
+  "peerDependencies": {
+    "@traq-markdown-engine/commonmark-plugin": "0.1.0",
+    "@traq-markdown-engine/core": "0.1.0"
+  },
+  "engines": {
+    "node": ">=24"
+  }
+}