@runtypelabs/persona 3.27.0 → 3.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runtypelabs/persona",
-  "version": "3.27.0",
+  "version": "3.29.0",
   "description": "Themeable, pluggable streaming agent widget for websites, in plain JS with support for voice input and reasoning / tool output.",
   "type": "module",
   "main": "dist/index.cjs",
@@ -17,6 +17,11 @@
       "import": "./dist/theme-reference.js",
       "require": "./dist/theme-reference.cjs"
     },
+    "./codegen": {
+      "types": "./dist/codegen.d.ts",
+      "import": "./dist/codegen.js",
+      "require": "./dist/codegen.cjs"
+    },
     "./theme-editor": {
       "types": "./dist/theme-editor.d.ts",
       "import": "./dist/theme-editor.js",
@@ -99,12 +104,13 @@
     "access": "public"
   },
   "scripts": {
-    "build": "rimraf dist && pnpm run build:styles && pnpm run build:client && pnpm run build:installer && pnpm run build:launcher && pnpm run build:theme-ref && pnpm run build:theme-editor && pnpm run build:testing && pnpm run build:smart-dom-reader && pnpm run build:animations",
+    "build": "rimraf dist && pnpm run build:styles && pnpm run build:client && pnpm run build:installer && pnpm run build:launcher && pnpm run build:theme-ref && pnpm run build:codegen && pnpm run build:theme-editor && pnpm run build:testing && pnpm run build:smart-dom-reader && pnpm run build:animations",
     "build:theme-editor": "tsup src/theme-editor.ts --format esm,cjs --minify --dts --out-dir dist --no-splitting",
     "build:testing": "tsup src/testing.ts --format esm,cjs --minify --dts --out-dir dist --no-splitting",
     "build:smart-dom-reader": "tsup src/smart-dom-reader.ts --format esm,cjs --minify --dts --out-dir dist --no-splitting",
     "build:animations": "tsup src/animations/glyph-cycle.ts src/animations/wipe.ts --format esm,cjs --minify --dts --out-dir dist/animations --no-splitting",
     "build:theme-ref": "tsup src/theme-reference.ts --format esm,cjs --minify --dts",
+    "build:codegen": "tsup src/codegen.ts --format esm,cjs --minify --dts",
     "build:styles": "node -e \"const fs=require('fs');fs.mkdirSync('dist',{recursive:true});fs.copyFileSync('src/styles/widget.css','dist/widget.css');\"",
     "build:client": "tsup src/index.ts --format esm,cjs --minify --sourcemap --splitting false --dts --loader \".css=text\" && tsup src/index-global.ts --format iife --global-name AgentWidget --minify --sourcemap --splitting false --out-dir dist --loader \".css=text\" && node -e \"const fs=require('fs');for(const ext of ['.global.js','.global.js.map']){const from='dist/index-global'+ext;if(fs.existsSync(from))fs.renameSync(from,'dist/index'+ext);}\"",
     "build:installer": "tsup src/install.ts --format iife --global-name SiteAgentInstaller --out-dir dist --minify --sourcemap --no-splitting",

package/src/codegen.test.ts

@@ -0,0 +1,82 @@
+import { describe, it, expect } from "vitest";
+import { generateCodeSnippet as fromSubpath } from "./codegen";
+import { generateCodeSnippet as fromInternal } from "./utils/code-generators";
+import { VERSION } from "./version";
+
+// The `@runtypelabs/persona/codegen` subpath is the server/Worker-safe entry for
+// snippet generation. It must expose the exact same generator as the internal
+// module (and, transitively, the main barrel) — no fork, no drift.
+describe("codegen subpath", () => {
+  const config = {
+    apiUrl: "https://api.example.com/chat",
+    clientToken: "ct_test_123",
+    launcher: { enabled: true, title: "Chat" },
+  };
+
+  it("re-exports the same generateCodeSnippet implementation", () => {
+    expect(fromSubpath).toBe(fromInternal);
+  });
+
+  it("produces identical output via the subpath for every format", () => {
+    const formats = [
+      "esm",
+      "script-installer",
+      "script-manual",
+      "script-advanced",
+      "react-component",
+      "react-advanced",
+    ] as const;
+    for (const format of formats) {
+      expect(fromSubpath(config, format)).toBe(fromInternal(config, format));
+    }
+  });
+
+  it("pins the installer CDN url to the package version (not @latest)", () => {
+    const code = fromSubpath(config, "script-installer");
+    expect(code).toContain(`@runtypelabs/persona@${VERSION}/dist/install.global.js`);
+    expect(code).not.toContain("@latest");
+  });
+
+  describe("mount target option", () => {
+    it("defaults to body when no target is given", () => {
+      expect(fromSubpath(config, "react-component")).toContain("target: 'body'");
+      expect(fromSubpath(config, "script-manual")).toContain("target: 'body'");
+      // installer omits the target key entirely (installer falls back to body)
+      expect(fromSubpath(config, "script-installer")).not.toContain('"target"');
+    });
+
+    it("emits the selector as the initAgentWidget target for code formats", () => {
+      const opts = { target: "#chat" };
+      expect(fromSubpath(config, "esm", opts)).toContain("target: '#chat'");
+      expect(fromSubpath(config, "react-component", opts)).toContain("target: '#chat'");
+      expect(fromSubpath(config, "script-manual", opts)).toContain("target: '#chat'");
+    });
+
+    it("serializes the selector as a top-level installer option (sibling of config)", () => {
+      // install.ts reads the mount point from the TOP LEVEL of data-config, not
+      // from inside the widget config. Parse the emitted data-config and assert
+      // the structure so a regression to the nested form is caught.
+      const code = fromSubpath(config, "script-installer", { target: "#chat" });
+      const json = code.match(/data-config='([^']*)'/)?.[1];
+      expect(json).toBeTruthy();
+      const parsed = JSON.parse(json!);
+      expect(parsed.target).toBe("#chat");
+      expect(parsed.config).toBeTruthy();
+      // target must NOT be buried inside the widget config (where it's ignored)
+      expect(parsed.config.target).toBeUndefined();
+    });
+
+    it("keeps target as a top-level sibling alongside windowKey", () => {
+      const code = fromSubpath(config, "script-installer", { target: "#chat", windowKey: "myWidget" });
+      const parsed = JSON.parse(code.match(/data-config='([^']*)'/)![1]);
+      expect(parsed.target).toBe("#chat");
+      expect(parsed.windowKey).toBe("myWidget");
+      expect(parsed.config).toBeTruthy();
+    });
+
+    it("escapes single quotes in the selector so it can't break the literal", () => {
+      const code = fromSubpath(config, "react-component", { target: "[data-x='y']" });
+      expect(code).toContain("target: '[data-x=\\'y\\']'");
+    });
+  });
+});

package/src/codegen.ts

@@ -0,0 +1,20 @@
+/**
+ * Pure code-snippet generation entry (`@runtypelabs/persona/codegen`).
+ *
+ * `generateCodeSnippet` is pure string-templating — it builds install snippets
+ * from a widget config and depends only on a type import + the `VERSION`
+ * constant. The main `index.ts` barrel re-exports it too, but that barrel pulls
+ * in the full widget runtime (`index-core` → idiomorph / marked / DOM), which is
+ * unacceptable for server/Worker consumers that only need snippet strings.
+ *
+ * This subpath exposes the generator on its own (mirroring `theme-reference`) so
+ * those consumers import it without dragging in the browser runtime. Existing
+ * npm consumers keep using the barrel export unchanged.
+ */
+
+export { generateCodeSnippet } from "./utils/code-generators";
+export type {
+  CodeFormat,
+  CodeGeneratorHooks,
+  CodeGeneratorOptions
+} from "./utils/code-generators";

package/src/utils/code-generators.ts

@@ -141,6 +141,16 @@ export type CodeGeneratorOptions = {
    * Only affects script formats (script-installer, script-manual, script-advanced).
    */
   windowKey?: string;
+
+  /**
+   * CSS selector for the mount target. When omitted, the widget mounts on
+   * `body` (the existing default). When provided, the generated snippet mounts
+   * into that element: ESM / React / manual / advanced formats emit it as the
+   * `target` argument to `initAgentWidget()`, and `script-installer` serializes
+   * it into `data-config` (the installer reads `config.target`).
+   * @default "body"
+   */
+  target?: string;
 };
 
 // Internal type for normalized hooks (always strings)
@@ -540,6 +550,15 @@ function appendSerializableObjectBlock(
   lines.push(`${indent}},`);
 }
 
+/**
+ * Resolve the mount-target selector for a single-quoted JS string context.
+ * Defaults to `body` and escapes backslashes / single quotes so an arbitrary
+ * selector can't break out of the emitted `target: '...'` literal.
+ */
+function emitTargetSelector(options?: CodeGeneratorOptions): string {
+  return (options?.target ?? "body").replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+}
+
 export function generateCodeSnippet(
   config: any,
   format: CodeFormat = "esm",
@@ -580,7 +599,7 @@ function generateESMCode(config: any, options?: CodeGeneratorOptions): string {
     "import { initAgentWidget, markdownPostprocessor } from '@runtypelabs/persona';",
     "",
     "initAgentWidget({",
-    "  target: 'body',",
+    `  target: '${emitTargetSelector(options)}',`,
     "  config: {"
   ];
 
@@ -726,7 +745,7 @@ function generateReactComponentCode(config: any, options?: CodeGeneratorOptions)
     "    let handle: AgentWidgetInitHandle | null = null;",
     "",
     "    handle = initAgentWidget({",
-    "      target: 'body',",
+    `      target: '${emitTargetSelector(options)}',`,
     "      config: {"
   ];
 
@@ -990,7 +1009,7 @@ function generateReactAdvancedCode(config: any, options?: CodeGeneratorOptions):
     "    };",
     "",
     "    handle = initAgentWidget({",
-    "      target: 'body',",
+    `      target: '${emitTargetSelector(options)}',`,
     "      config: {"
   ];
 
@@ -1356,10 +1375,20 @@ function buildSerializableConfig(config: any): Record<string, any> {
 function generateScriptInstallerCode(config: any, options?: CodeGeneratorOptions): string {
   const serializableConfig = buildSerializableConfig(config);
 
-  // When windowKey is provided, nest the widget config under `config` so the
-  // install script's parsedConfig.config detection picks it up alongside windowKey.
-  const payload = options?.windowKey
-    ? { config: serializableConfig, windowKey: options.windowKey }
+  // `windowKey` and `target` are INSTALLER options, not widget-config fields.
+  // install.ts reads them from the top level of data-config: the nested-`config`
+  // branch hoists every sibling key (Object.assign(scriptConfig, parsed)), while
+  // a flat payload becomes the widget config wholesale and its siblings are
+  // ignored. So whenever either is set we emit the nested `{ config, ...}` form
+  // with the option as a SIBLING of `config` — nesting `target` inside the
+  // widget config would leave the widget mounted on `body`.
+  const needsWrapper = Boolean(options?.windowKey || options?.target);
+  const payload = needsWrapper
+    ? {
+        config: serializableConfig,
+        ...(options?.windowKey ? { windowKey: options.windowKey } : {}),
+        ...(options?.target ? { target: options.target } : {}),
+      }
     : serializableConfig;
 
   // Escape single quotes in JSON for HTML attribute
@@ -1383,7 +1412,7 @@ function generateScriptManualCode(config: any, options?: CodeGeneratorOptions):
     "<!-- Initialize widget -->",
     "<script>",
     "  var handle = window.AgentWidget.initAgentWidget({",
-    "    target: 'body',",
+    `    target: '${emitTargetSelector(options)}',`,
     ...(options?.windowKey ? [`    windowKey: '${options.windowKey}',`] : []),
     "    config: {"
   ];
@@ -1735,7 +1764,7 @@ function generateScriptAdvancedCode(config: any, options?: CodeGeneratorOptions)
     "",
     "    // Initialize widget",
     "    var handle = agentWidget.initAgentWidget({",
-    "      target: 'body',",
+    `      target: '${emitTargetSelector(options)}',`,
     "      useShadowDom: false,",
     ...(options?.windowKey ? [`      windowKey: '${options.windowKey}',`] : []),
     "      config: widgetConfig",