@antglobal/copilot-cards-core 1.0.0 → 1.0.2

package/README.md

@@ -1 +1,152 @@
-# Marmot NPM
+# @antglobal/copilot-cards-core
+
+Core logic for schema-driven cards in AI conversations. This package has no UI or DOM dependency and can run in browsers, Node.js, WebViews, and mini-program runtimes.
+
+It provides schema parsing, expression resolution, action execution, lifecycle management, streaming commands, legacy-schema conversion, and the shared built-in icon registry used by the Web and mini-program renderers.
+
+## Installation
+
+```bash
+npm install @antglobal/copilot-cards-core
+```
+
+## Quick start
+
+```ts
+import {
+  parseSchema,
+  resolveExpression,
+  validateSchema,
+  type CardSchema,
+} from "@antglobal/copilot-cards-core";
+
+const schema: CardSchema = {
+  version: "1.0",
+  rootID: "root",
+  elements: {
+    root: {
+      id: "root",
+      type: "Text",
+      props: {
+        content: { type: "static", value: "Hello, Copilot Cards!" },
+      },
+    },
+  },
+  variables: {
+    user: { name: "Alice" },
+  },
+};
+
+const errors = validateSchema(schema);
+if (errors.length > 0) {
+  throw new Error(errors.join("\n"));
+}
+
+const tree = parseSchema(schema);
+const greeting = resolveExpression("Hello, ${user.name}!", schema.variables);
+
+console.log(tree, greeting);
+```
+
+## Capabilities
+
+| Module | Purpose |
+| --- | --- |
+| Schema parser | Validates, normalizes, and converts flat schemas into render trees |
+| Expression engine | Resolves `${path}` templates, ternaries, logical expressions, and comparisons |
+| Action runner | Executes declarative action chains in order |
+| Action registry | Registers custom action handlers, optionally scoped by bot ID |
+| Action provider | Resolves named action chains supplied by the host |
+| Lifecycle manager | Coordinates `onMount`, `onExposed`, and `onDestroy` hooks |
+| Streaming engine | Parses and applies incremental card commands and A2UI envelopes |
+| Legacy compatibility | Detects and converts legacy card schemas |
+| Icon registry | Exposes shared built-in icon names and SVG definitions |
+
+## Expressions
+
+```ts
+import {
+  interpolate,
+  resolveDeep,
+  resolveExpression,
+} from "@antglobal/copilot-cards-core";
+
+const context = {
+  user: { name: "Alice", role: "admin" },
+  count: 3,
+};
+
+resolveExpression("${user.name}", context); // "Alice"
+resolveExpression("${count > 2}", context); // true
+resolveExpression(
+  "${user.role === 'admin' ? 'Administrator' : 'User'}",
+  context,
+); // "Administrator"
+interpolate("Hello, ${user.name}!", context); // "Hello, Alice!"
+resolveDeep({ title: "${user.name}", visible: "${count > 0}" }, context);
+```
+
+## Actions
+
+Built-in action types are host-independent. The host supplies capabilities such as `fetch`, navigation, toast notifications, clipboard access, and event emission through an `ActionRunnerContext`.
+
+| Action | Behavior |
+| --- | --- |
+| `emit` | Emits an event to the host |
+| `request` | Runs an HTTP request with response mapping, polling, timeout, and deduplication support |
+| `setVariable` | Updates a card variable |
+| `toast` | Requests a toast notification |
+| `url` | Requests navigation |
+| `copy` | Requests clipboard access |
+
+Register a custom action handler:
+
+```ts
+import {
+  registerActionHandler,
+  runActionSteps,
+} from "@antglobal/copilot-cards-core";
+
+registerActionHandler("support-bot", "trackEvent", async (step) => {
+  console.log("track", step.params);
+});
+
+await runActionSteps(
+  [{ type: "trackEvent", params: { event: "card_opened" } }],
+  { botId: "support-bot", variables: {} },
+);
+```
+
+## Streaming
+
+The package exports `StreamingParser`, `StreamingEngine`, `extractPartialSchema`, and A2UI conversion helpers for incrementally generated cards.
+
+```ts
+import {
+  StreamingEngine,
+  StreamingParser,
+} from "@antglobal/copilot-cards-core";
+
+const parser = new StreamingParser();
+const engine = new StreamingEngine({
+  onSurfaceCreated: (surfaceId) => console.log("created", surfaceId),
+  onComponentsUpdated: (surfaceId, changes) =>
+    console.log("components", surfaceId, changes),
+  onDataModelUpdated: (surfaceId, path, value) =>
+    console.log("data", surfaceId, path, value),
+  onContentAppended: (surfaceId, elementId, content) =>
+    console.log("content", surfaceId, elementId, content),
+  onSurfaceDeleted: (surfaceId) => console.log("deleted", surfaceId),
+});
+
+engine.applyBatch(parser.parse(chunk));
+```
+
+## Related packages
+
+- `@antglobal/copilot-cards-web` — Web Component renderer for browser and WebView applications.
+- `@antglobal/copilot-cards-mini-program` — native renderer for Alipay and WeChat mini-programs.
+
+## License
+
+MIT