@actioneer/ads 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Glitchcraft, Inc.
+
+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/bin/ads-init.mjs

@@ -0,0 +1,314 @@
+#!/usr/bin/env node
+/**
+ * `npx @actioneer/ads init` — idempotent bootstrap for a consumer repo.
+ *
+ * Modeled as a PURE write-plan (`repo state → ordered list of edits`) plus a
+ * thin applier that performs the IO. The plan does the deciding; the applier
+ * does the doing. A second run on an already-configured repo yields an empty
+ * plan and reports "nothing to do."
+ *
+ * Edits it plans:
+ *   • install `@actioneer/ads` (+ `motion` for the reduced-motion provider)
+ *   • inject `@import "@actioneer/ads/styles.css";` right after
+ *     `@import "tailwindcss";` in the global stylesheet
+ *   • scaffold the three required providers (TooltipProvider, ToastProvider,
+ *     <MotionConfig reducedMotion="user">) as `app/providers.tsx` and wrap the
+ *     root layout's children with them
+ *   • drop a consumer-mode `ads-lint.config.mjs`
+ *     (`libraryPackage: "@actioneer/ads"`, `libraryRoot: null`)
+ *
+ * Per the DES-13 testing decision, the write-plan is exercised end-to-end by a
+ * manual run rather than dedicated unit tests this pass.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+
+const PKG = "@actioneer/ads";
+const STYLE_IMPORT = `@import "${PKG}/styles.css";`;
+
+// ── pure write-plan ──────────────────────────────────────────────────────────
+
+/**
+ * @typedef {Object} RepoState
+ * @property {Record<string,string>} dependencies  merged deps+devDeps of the consumer
+ * @property {string|null} globalCssPath           repo-relative path to the global stylesheet (or null)
+ * @property {string|null} globalCssContent
+ * @property {string|null} layoutPath              repo-relative path to the root layout (or null)
+ * @property {string|null} layoutContent
+ * @property {boolean} hasAdsLintConfig
+ *
+ * @typedef {Object} Edit
+ * @property {"install"|"write-file"|"edit-file"|"manual"} type
+ * @property {string} title                        human-readable description (idempotency = title uniqueness)
+ * @property {string} [path]
+ * @property {string} [content]                    write-file: full file content
+ * @property {string} [find]                       edit-file: substring to replace
+ * @property {string} [replace]                    edit-file: replacement text
+ * @property {number} [findIndex]                  edit-file: positional replace offset (disambiguates repeated tokens)
+ * @property {string} [addImport]                  edit-file: import line to prepend if absent
+ * @property {string[]} [packages]                 install: package specifiers
+ */
+
+/** @param {RepoState} state @returns {Edit[]} */
+export function planInit(state) {
+  const edits = [];
+
+  // 1. Install the package (+ motion peer for the reduced-motion provider).
+  const missing = ["@actioneer/ads", "motion"].filter((p) => !state.dependencies?.[p]);
+  if (missing.length) {
+    edits.push({ type: "install", title: `install ${missing.join(", ")}`, packages: missing });
+  }
+
+  // 2. Inject the styles.css import IMMEDIATELY AFTER `@import "tailwindcss"`.
+  //    Order is load-bearing: styles.css before tailwindcss leaves its @theme
+  //    inert (see CONSUMING.md §2). If there's no tailwindcss import to anchor
+  //    to, we do NOT guess a position — we emit a manual instruction so we never
+  //    write the broken order.
+  if (state.globalCssPath != null && state.globalCssContent != null) {
+    if (!state.globalCssContent.includes(STYLE_IMPORT)) {
+      const twMatch = state.globalCssContent.match(/@import\s+["']tailwindcss["'][^;]*;/);
+      if (twMatch) {
+        edits.push({
+          type: "edit-file",
+          title: `inject ${PKG}/styles.css import into ${state.globalCssPath}`,
+          path: state.globalCssPath,
+          find: twMatch[0],
+          replace: `${twMatch[0]}\n${STYLE_IMPORT}`,
+        });
+      } else {
+        edits.push({
+          type: "manual",
+          title: `add \`@import "tailwindcss";\` then \`${STYLE_IMPORT}\` (in that order) to ${state.globalCssPath}`,
+        });
+      }
+    }
+  } else {
+    edits.push({
+      type: "manual",
+      title: `add \`@import "tailwindcss";\` then \`${STYLE_IMPORT}\` to your global stylesheet`,
+    });
+  }
+
+  // 3. Scaffold the providers file + wrap the layout.
+  if (state.layoutPath != null) {
+    const dir = path.posix.dirname(toPosix(state.layoutPath));
+    const providersPath = path.posix.join(dir, "providers.tsx");
+    if (!fileExistsInState(state, providersPath)) {
+      edits.push({
+        type: "write-file",
+        title: `scaffold providers at ${providersPath}`,
+        path: providersPath,
+        content: PROVIDERS_FILE,
+      });
+    }
+    if (state.layoutContent != null && !state.layoutContent.includes("<Providers>")) {
+      const child = findJsxChildren(state.layoutContent);
+      if (child) {
+        edits.push({
+          type: "edit-file",
+          title: `wrap the root layout children with <Providers> in ${state.layoutPath}`,
+          path: state.layoutPath,
+          find: child,
+          findIndex: state.layoutContent.indexOf(child, state.layoutContent.indexOf("return")),
+          replace: `<Providers>${child}</Providers>`,
+          addImport: `import { Providers } from "./providers";`,
+        });
+      } else {
+        edits.push({
+          type: "manual",
+          title: `wrap your app root's children with <Providers> (from ./providers)`,
+        });
+      }
+    }
+  } else {
+    edits.push({
+      type: "write-file",
+      title: "scaffold providers at app/providers.tsx",
+      path: "app/providers.tsx",
+      content: PROVIDERS_FILE,
+    });
+    edits.push({
+      type: "manual",
+      title: "wrap your app root's children with <Providers> (from ./providers)",
+    });
+  }
+
+  // 4. Drop a consumer-mode ads-lint config.
+  if (!state.hasAdsLintConfig) {
+    edits.push({
+      type: "write-file",
+      title: "drop consumer-mode ads-lint.config.mjs",
+      path: "ads-lint.config.mjs",
+      content: ADS_LINT_CONFIG,
+    });
+  }
+
+  return edits;
+}
+
+/**
+ * Locate the JSX `{children}` render expression in a root layout — NOT the
+ * destructuring parameter `({ children }: …)` or a type annotation. Returns the
+ * exact token text, or null if none is safely identifiable.
+ */
+export function findJsxChildren(source) {
+  for (const m of source.matchAll(/\{\s*children\s*\}/g)) {
+    const start = m.index;
+    const end = start + m[0].length;
+    // Nearest non-space neighbors.
+    let b = start - 1;
+    while (b >= 0 && /\s/.test(source[b])) b--;
+    let a = end;
+    while (a < source.length && /\s/.test(source[a])) a++;
+    const prev = source[b];
+    const next = source[a];
+    // Skip the destructuring param `({ children }` and any `{ children }:` type.
+    if (prev === "(" || prev === "," || next === ":") continue;
+    return m[0];
+  }
+  return null;
+}
+
+const PROVIDERS_FILE = `"use client";
+
+// Required ADS providers — wrap the app root once. Without TooltipProvider the
+// vendored tooltip/attachment chips crash; ToastProvider is needed to render
+// toasts; MotionConfig reducedMotion="user" honors the OS setting everywhere.
+import { TooltipProvider, ToastProvider } from "${PKG}";
+import { MotionConfig } from "motion/react";
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <MotionConfig reducedMotion="user">
+      <ToastProvider>
+        <TooltipProvider>{children}</TooltipProvider>
+      </ToastProvider>
+    </MotionConfig>
+  );
+}
+`;
+
+const ADS_LINT_CONFIG = `// @actioneer/ads-lint — consumer mode. Every file is a consumer, so the
+// barrel / deep-import / external-UI rules apply everywhere. See the ADS
+// import contract: import the exact named export from "${PKG}"; never
+// deep-import, alias, or hand-roll a copy.
+export default {
+  imports: {
+    libraryPackage: "${PKG}",
+    libraryRoot: null,
+  },
+};
+`;
+
+// ── thin applier (IO) ────────────────────────────────────────────────────────
+
+const CANDIDATE_CSS = [
+  "app/globals.css",
+  "src/app/globals.css",
+  "styles/globals.css",
+  "app/global.css",
+  "src/styles/globals.css",
+];
+const CANDIDATE_LAYOUT = ["app/layout.tsx", "src/app/layout.tsx", "app/layout.jsx", "src/app/layout.jsx"];
+
+function toPosix(p) {
+  return p.split(path.sep).join("/");
+}
+function fileExistsInState(state, relPosix) {
+  return state._existing?.has(relPosix) ?? false;
+}
+
+function readRepoState(cwd) {
+  const read = (rel) => {
+    const abs = path.join(cwd, rel);
+    return fs.existsSync(abs) ? fs.readFileSync(abs, "utf8") : null;
+  };
+  const pkgRaw = read("package.json");
+  const pkg = pkgRaw ? JSON.parse(pkgRaw) : {};
+  const dependencies = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
+
+  const globalCssPath = CANDIDATE_CSS.find((p) => fs.existsSync(path.join(cwd, p))) ?? null;
+  const layoutPath = CANDIDATE_LAYOUT.find((p) => fs.existsSync(path.join(cwd, p))) ?? null;
+
+  const _existing = new Set();
+  for (const p of [...CANDIDATE_CSS, ...CANDIDATE_LAYOUT, "ads-lint.config.mjs", "app/providers.tsx", "src/app/providers.tsx"]) {
+    if (fs.existsSync(path.join(cwd, p))) _existing.add(p);
+  }
+
+  return {
+    dependencies,
+    globalCssPath,
+    globalCssContent: globalCssPath ? read(globalCssPath) : null,
+    layoutPath,
+    layoutContent: layoutPath ? read(layoutPath) : null,
+    hasAdsLintConfig:
+      fs.existsSync(path.join(cwd, "ads-lint.config.mjs")) || fs.existsSync(path.join(cwd, "ads-lint.config.js")),
+    _existing,
+  };
+}
+
+function applyEdit(cwd, edit) {
+  const abs = edit.path ? path.join(cwd, edit.path) : null;
+  switch (edit.type) {
+    case "install": {
+      console.log(`  → npm install ${edit.packages.join(" ")}`);
+      execFileSync("npm", ["install", ...edit.packages], { cwd, stdio: "inherit" });
+      return;
+    }
+    case "write-file": {
+      fs.mkdirSync(path.dirname(abs), { recursive: true });
+      fs.writeFileSync(abs, edit.content);
+      console.log(`  → wrote ${edit.path}`);
+      return;
+    }
+    case "edit-file": {
+      let content = fs.readFileSync(abs, "utf8");
+      if (typeof edit.findIndex === "number" && edit.findIndex >= 0) {
+        // Positional replace — avoids clobbering an earlier identical token
+        // (e.g. the layout's `{ children }` destructuring parameter).
+        content =
+          content.slice(0, edit.findIndex) +
+          edit.replace +
+          content.slice(edit.findIndex + edit.find.length);
+      } else {
+        content = content.replace(edit.find, edit.replace);
+      }
+      if (edit.addImport && !content.includes(edit.addImport)) content = `${edit.addImport}\n${content}`;
+      fs.writeFileSync(abs, content);
+      console.log(`  → edited ${edit.path}`);
+      return;
+    }
+    case "manual": {
+      console.log(`  → manual: ${edit.title}`);
+      return;
+    }
+  }
+}
+
+function main() {
+  const cmd = process.argv[2];
+  const cwd = process.cwd();
+  if (cmd && cmd !== "init") {
+    console.error(`ads: unknown command "${cmd}". Usage: npx ${PKG} init`);
+    process.exit(1);
+  }
+
+  const state = readRepoState(cwd);
+  const edits = planInit(state);
+
+  if (edits.length === 0) {
+    console.log(`${PKG} init: nothing to do — already configured.`);
+    return;
+  }
+
+  console.log(`${PKG} init: applying ${edits.length} edit(s)…`);
+  for (const edit of edits) applyEdit(cwd, edit);
+  console.log(`\n${PKG} init: done. Import components with \`import { Button } from "${PKG}";\``);
+}
+
+// Only run the applier when invoked as a CLI (keeps planInit importable/pure).
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main();
+}

package/components/accordion.d.ts

@@ -0,0 +1,13 @@
+import * as React from "react";
+type AccordionType = "single" | "multiple";
+export interface AccordionProps extends React.HTMLAttributes<HTMLDivElement> {
+    type?: AccordionType;
+    defaultValue?: string | string[];
+}
+export declare const Accordion: React.ForwardRefExoticComponent<AccordionProps & React.RefAttributes<HTMLDivElement>>;
+export interface AccordionItemProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title"> {
+    value: string;
+    title: React.ReactNode;
+}
+export declare const AccordionItem: React.ForwardRefExoticComponent<AccordionItemProps & React.RefAttributes<HTMLDivElement>>;
+export {};

package/components/accordion.js

@@ -0,0 +1,91 @@
+"use client";
+import { jsx as n, jsxs as h } from "react/jsx-runtime";
+import * as r from "react";
+import { ChevronDown as I } from "../lib/icons.js";
+import { cn as c } from "../lib/cn.js";
+const b = r.createContext(
+  null
+);
+function A(s) {
+  const e = r.useContext(b);
+  if (!e)
+    throw new Error(`<${s}> must be used within <Accordion>`);
+  return e;
+}
+const N = r.forwardRef(
+  ({ className: s, type: e = "single", defaultValue: t, children: u, ...f }, g) => {
+    const d = r.useId(), [a, l] = r.useState(() => t === void 0 ? [] : Array.isArray(t) ? t : [t]), i = r.useCallback(
+      (o) => {
+        l((x) => {
+          const p = x.includes(o);
+          return e === "single" ? p ? [] : [o] : p ? x.filter((w) => w !== o) : [...x, o];
+        });
+      },
+      [e]
+    ), m = r.useMemo(
+      () => ({ openItems: a, toggle: i, baseId: d }),
+      [a, i, d]
+    );
+    return /* @__PURE__ */ n(b.Provider, { value: m, children: /* @__PURE__ */ n(
+      "div",
+      {
+        ref: g,
+        className: c(s),
+        ...f,
+        children: u
+      }
+    ) });
+  }
+);
+N.displayName = "Accordion";
+const y = r.forwardRef(({ className: s, value: e, title: t, children: u, ...f }, g) => {
+  const { openItems: d, toggle: a, baseId: l } = A("AccordionItem"), i = d.includes(e), m = `${l}-trigger-${e}`, o = `${l}-panel-${e}`;
+  return /* @__PURE__ */ h("div", { ref: g, className: c(s), ...f, children: [
+    /* @__PURE__ */ n("h3", { className: "flex", children: /* @__PURE__ */ h(
+      "button",
+      {
+        type: "button",
+        id: m,
+        "aria-expanded": i,
+        "aria-controls": o,
+        onClick: () => a(e),
+        className: c(
+          "flex w-full items-center justify-between py-4 text-left font-medium",
+          "outline-none focus-visible:ring-3 focus-visible:ring-ring rounded-sm",
+          "transition-colors hover:text-foreground"
+        ),
+        children: [
+          t,
+          /* @__PURE__ */ n(
+            I,
+            {
+              "aria-hidden": !0,
+              className: c(
+                "size-4 shrink-0 text-muted-foreground transition-transform duration-(--duration-normal) ease-out motion-reduce:transition-none",
+                i && "rotate-180"
+              )
+            }
+          )
+        ]
+      }
+    ) }),
+    /* @__PURE__ */ n(
+      "div",
+      {
+        id: o,
+        role: "region",
+        "aria-labelledby": m,
+        className: c(
+          "grid",
+          i ? "grid-rows-[1fr]" : "grid-rows-[0fr]"
+        ),
+        children: /* @__PURE__ */ n("div", { className: "overflow-hidden", children: /* @__PURE__ */ n("div", { className: "pb-4 text-xs text-muted-foreground", children: u }) })
+      }
+    )
+  ] });
+});
+y.displayName = "AccordionItem";
+export {
+  N as Accordion,
+  y as AccordionItem
+};

package/components/agents-ui/agent-audio-visualizer-aura.d.ts

@@ -0,0 +1,11 @@
+import { VoiceVisualizerColor, VoiceVisualizerDriver } from '../../hooks/agents-ui/voice-visualizer-types';
+import * as React from "react";
+export interface AgentAudioVisualizerAuraProps extends Omit<React.ComponentPropsWithoutRef<"div">, "color">, VoiceVisualizerDriver {
+    /** Normalized RGB shader color. */
+    color?: VoiceVisualizerColor;
+    /** Hue variation across aura layers. */
+    colorShift?: number;
+    themeMode?: "dark" | "light";
+}
+/** Internal ADS port of LiveKit Agents UI's Aura visualizer. */
+export declare const AgentAudioVisualizerAura: React.ForwardRefExoticComponent<AgentAudioVisualizerAuraProps & React.RefAttributes<HTMLDivElement>>;