@hyacine/core 0.0.1

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@hyacine/core",
+  "version": "0.0.1",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./config": {
+      "types": "./src/config.ts",
+      "default": "./src/config.ts"
+    },
+    "./plugin": {
+      "types": "./src/plugin.d.ts",
+      "default": "./src/plugin.d.ts"
+    },
+    "./constants": {
+      "types": "./src/constants.ts",
+      "default": "./src/constants.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "lint": "bunx --bun oxlint --type-aware --type-check . --fix",
+    "format": "bunx oxfmt ."
+  },
+  "devDependencies": {
+    "typescript": "^5"
+  }
+}

package/src/config.ts

@@ -0,0 +1,33 @@
+import type { PluginManifest } from "./plugin";
+
+export type PluginFunction<O = any> = (options: O) => PluginManifest;
+
+export function definePlugin(manifest: PluginManifest): PluginManifest {
+  return manifest;
+}
+
+export type injectPoint =
+  | "head"
+  | "layout"
+  | "right-nav"
+  | "left-nav"
+  | "post-meta"
+  | "sidebar"
+  | "footer"
+  | "widgets"
+  | "post-footer"
+  | "comment"
+  | "footer-status"
+  | "toolbar"
+  | "segments-sticky";
+
+export type injectPoints = Record<string, string> & Partial<Record<injectPoint, string>>;
+
+export interface HyacinePluginSystemConfig {
+  injectPoints: injectPoints;
+  plugins: Array<PluginManifest>;
+}
+
+export function defineConfig<T extends HyacinePluginSystemConfig>(config: T): T {
+  return config;
+}

package/src/constants.ts

@@ -0,0 +1,5 @@
+export const PLUGIN_API_VERSION = {
+  major: 0,
+  minor: 0,
+  patch: 1,
+};

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from "./config";
+export * from "./constants";
+export * from "./plugin";

package/src/plugin.ts

@@ -0,0 +1,91 @@
+import type { injectPoint } from "./config";
+
+/**
+ * 对于一个插件而言，其渲染类型只能是以下三种之一
+ * - runtime-only: 仅运行时渲染，入口点只能包括一个或多个 js/ts 文件，不能包含任何模板文件
+ * - custom-element: 基于 Web Components 的渲染，入口点可以包含一个或多个 js/ts 文件和编译为 Web Component 的模板文件（或 Web Component本身），可以指定 universal 平台
+ * - ssr: 服务器端渲染，入口点可以包含一个或多个 js/ts 文件和用于服务器端渲染的模板文件，必须针对每个平台指定不同的入口点
+ */
+export type pluginRenderType = "runtime-only" | "custom-element" | "ssr";
+
+/**
+ * 插件支持的平台类型
+ * - astro: 适用于 Astro 框架的插件
+ * - valaxy: 适用于 Valaxy 框架的插件
+ * - universal: 通用插件，适用于所有支持插件的框架
+ */
+export type pluginPlatformType = "astro" | "valaxy" | "universal";
+
+export interface PluginManifestBase {
+  name: string;
+  version: string;
+  /**
+   * 此处接受 package.json 式的 semver 版本范围字符串，例如 ^0.0.1、~1.2.0 等
+   * 用于指定该插件兼容的插件 API 版本范围
+   * 如果未指定，则默认为 * ，表示兼容所有版本
+   */
+  compatibleAPIPattern?: string;
+  /**
+   * 插件的最小渲染能力，决定了插件可以包含的入口点类型
+   */
+  minRenderCapability: pluginRenderType;
+}
+
+export interface InjectEntry {
+  injectPoint?: injectPoint | (string & {});
+  type: "runtime-only" | "custom-element" | "ssr";
+  path: string;
+  name: string;
+}
+
+export interface RuntimeOnlyEntry extends InjectEntry {
+  type: "runtime-only";
+  /**
+   * 传递给 runtime-only 插件 init 函数的配置选项
+   * 注意：options 值必须是可序列化的，避免传递函数、Symbol 等不可序列化的值
+   */
+  options?: Record<string, unknown>;
+}
+
+export interface RuntimeOnlyPluginManifest extends PluginManifestBase {
+  minRenderCapability: "runtime-only";
+  entry: RuntimeOnlyEntry[];
+}
+
+/**
+ * 基于 Web Components 的插件入口点
+ * 入口点将会在 Layout 内放置一个隐藏的 Astro 组件，以确保其在页面加载时进行 SSR 水合
+ */
+export interface CustomElementEntry extends InjectEntry {
+  type: "custom-element";
+  injectPoint: "layout";
+}
+
+export interface CustomElementPluginManifest extends PluginManifestBase {
+  minRenderCapability: "custom-element";
+  supportedPlatforms: pluginPlatformType[];
+  entry: Array<CustomElementEntry | RuntimeOnlyEntry>;
+}
+
+export interface SSREntry extends InjectEntry {
+  type: "ssr";
+  platform: pluginPlatformType;
+  injectPoint: string;
+  clientHydrationInstruction?: "load" | "idle" | "visible" | "media";
+  /**
+   * 传递给 SSR 组件的 props
+   * 注意：props 值必须是可序列化的，避免传递函数、Symbol 等不可序列化的值
+   */
+  props?: Record<string, unknown>;
+}
+
+export interface SSRPluginManifest extends PluginManifestBase {
+  minRenderCapability: "ssr";
+  supportedPlatforms: pluginPlatformType[];
+  entry: Array<SSREntry | CustomElementEntry | RuntimeOnlyEntry>;
+}
+
+export type PluginManifest =
+  | RuntimeOnlyPluginManifest
+  | CustomElementPluginManifest
+  | SSRPluginManifest;