@runtypelabs/persona 3.28.0 → 3.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runtypelabs/persona",
-  "version": "3.28.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",

package/src/codegen.test.ts

@@ -36,4 +36,47 @@ describe("codegen subpath", () => {
     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/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",