@tour-kit/studio 0.1.0

package/dist/index.js

@@ -0,0 +1,1743 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { defineCommand as defineCommand6, runMain } from "citty";
+
+// src/commands/add.ts
+import { existsSync as existsSync2 } from "fs";
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { dirname, join as join2, relative } from "path";
+
+// ../recipe/src/announcement.ts
+import { z as z2 } from "zod";
+
+// ../recipe/src/primitives.ts
+import { z } from "zod";
+var recipeId = z.string().regex(/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/);
+var semver = z.string().regex(/^\d+\.\d+\.\d+(?:-[\w.]+)?$/);
+var dateString = z.string().regex(/^\d{4}-\d{2}-\d{2}$/);
+var timeString = z.string().regex(/^\d{2}:\d{2}$/);
+var placement = z.enum([
+  "top",
+  "right",
+  "bottom",
+  "left",
+  "top-start",
+  "top-end",
+  "right-start",
+  "right-end",
+  "bottom-start",
+  "bottom-end",
+  "left-start",
+  "left-end"
+]);
+var mediaType = z.enum([
+  "auto",
+  "youtube",
+  "vimeo",
+  "loom",
+  "wistia",
+  "video",
+  "gif",
+  "lottie",
+  "image"
+]);
+var aspectRatio = z.enum([
+  "16/9",
+  "4/3",
+  "1/1",
+  "9/16",
+  "21/9",
+  "auto"
+]);
+var urlOrRootPath = z.string().min(1).refine(
+  (s) => s.startsWith("/") || z.url().safeParse(s).success,
+  "media src must be an absolute URL or root-relative path"
+);
+var media = z.object({
+  src: urlOrRootPath,
+  type: mediaType.optional(),
+  poster: z.string().optional(),
+  aspectRatio: aspectRatio.optional(),
+  alt: z.string().optional(),
+  title: z.string().optional(),
+  autoplay: z.boolean().optional(),
+  loop: z.boolean().optional(),
+  muted: z.boolean().optional()
+});
+
+// ../recipe/src/announcement.ts
+var announcementAction = z2.object({
+  label: z2.string(),
+  href: z2.string().optional(),
+  variant: z2.enum(["primary", "secondary", "ghost", "link"]).optional(),
+  dismissOnClick: z2.boolean().optional()
+});
+var announcementMedia = media.omit({ title: true });
+var spotlightOptions = z2.object({
+  targetSelector: z2.string(),
+  placement: z2.enum(["top", "right", "bottom", "left"]).optional(),
+  offset: z2.number().optional(),
+  showOverlay: z2.boolean().optional(),
+  overlayOpacity: z2.number().optional(),
+  closeOnOverlayClick: z2.boolean().optional()
+});
+var announcementComponent = z2.object({
+  kind: z2.literal("announcement"),
+  id: z2.string(),
+  variant: z2.enum(["modal", "slideout", "banner", "toast", "spotlight"]),
+  priority: z2.enum(["low", "normal", "high", "critical"]).optional(),
+  title: z2.string().optional(),
+  description: z2.string().optional(),
+  media: announcementMedia.optional(),
+  primaryAction: announcementAction.optional(),
+  secondaryAction: announcementAction.optional(),
+  schedule: z2.string().optional(),
+  autoShow: z2.boolean().optional(),
+  spotlightOptions: spotlightOptions.optional()
+});
+
+// ../recipe/src/branch.ts
+import { z as z3 } from "zod";
+var branchTarget = z3.lazy(
+  () => z3.union([
+    z3.string(),
+    z3.number().int(),
+    z3.enum(["next", "prev", "complete", "skip", "restart"]),
+    z3.object({
+      tour: z3.string(),
+      step: z3.union([z3.string(), z3.number().int()]).optional()
+    }),
+    z3.object({ skip: z3.number().int() }),
+    // biome-ignore lint/suspicious/noThenProperty: `then` mirrors @tour-kit/core's BranchWait wire-format field; renaming would break the projection
+    z3.object({ wait: z3.number().int(), then: branchTarget.optional() }),
+    z3.null()
+  ])
+);
+
+// ../recipe/src/checklist.ts
+import { z as z4 } from "zod";
+var checklistTask = z4.object({
+  id: z4.string(),
+  title: z4.string(),
+  description: z4.string().optional(),
+  media: media.optional(),
+  icon: z4.string().optional(),
+  action: z4.discriminatedUnion("type", [
+    z4.object({
+      type: z4.literal("navigate"),
+      url: z4.string(),
+      external: z4.boolean().optional()
+    }),
+    z4.object({ type: z4.literal("tour"), tourId: z4.string() }),
+    z4.object({ type: z4.literal("modal"), modalId: z4.string() })
+  ]).optional(),
+  dependsOn: z4.array(z4.string()).optional(),
+  completedWhen: z4.union([
+    z4.object({ tourCompleted: z4.string() }),
+    z4.object({ tourStarted: z4.string() }),
+    z4.object({ type: z4.literal("urlVisit"), urlPattern: z4.string() })
+  ]).optional(),
+  manualComplete: z4.boolean().optional()
+});
+var checklistComponent = z4.object({
+  kind: z4.literal("checklist"),
+  id: z4.string(),
+  title: z4.string(),
+  description: z4.string().optional(),
+  icon: z4.string().optional(),
+  tasks: z4.array(checklistTask).min(1),
+  dismissible: z4.boolean().optional(),
+  hideOnComplete: z4.boolean().optional()
+});
+
+// ../recipe/src/components.ts
+import { z as z6 } from "zod";
+
+// ../recipe/src/selector.ts
+import { z as z5 } from "zod";
+var selectorStrategy = z5.enum([
+  "data-tour-id",
+  "data-testid",
+  "role-name",
+  "css-path"
+]);
+var selectorMeta = z5.object({
+  strategy: selectorStrategy,
+  grade: z5.enum(["stable", "fragile"]),
+  brittleness: z5.number().int().min(0).max(100).optional()
+});
+var elementDescriptorSchema = z5.object({
+  tag: z5.string(),
+  attributes: z5.record(z5.string(), z5.string()),
+  role: z5.string().optional(),
+  accessibleName: z5.string().optional(),
+  cssPath: z5.string(),
+  cssPathDepth: z5.number().int().min(0),
+  usesNthChild: z5.boolean()
+});
+
+// ../recipe/src/components.ts
+var tourStep = z6.discriminatedUnion("kind", [
+  z6.object({
+    kind: z6.literal("visible"),
+    id: z6.string(),
+    target: z6.string(),
+    selectorMeta: selectorMeta.optional(),
+    title: z6.string().optional(),
+    content: z6.string(),
+    media: media.optional(),
+    placement: placement.optional(),
+    offset: z6.tuple([z6.number(), z6.number()]).optional(),
+    showNavigation: z6.boolean().optional(),
+    showClose: z6.boolean().optional(),
+    showProgress: z6.boolean().optional(),
+    advanceOn: z6.object({
+      event: z6.enum(["click", "input", "custom"]),
+      selector: z6.string().optional()
+    }).optional(),
+    onNext: branchTarget.optional(),
+    onPrev: branchTarget.optional(),
+    onAction: z6.record(z6.string(), branchTarget).optional()
+  }),
+  z6.object({ kind: z6.literal("hidden"), id: z6.string() })
+]);
+var tourComponent = z6.object({
+  kind: z6.literal("tour"),
+  id: z6.string(),
+  name: z6.string().optional(),
+  steps: z6.array(tourStep).min(1),
+  autoStart: z6.boolean().optional(),
+  startAt: z6.number().int().optional(),
+  keyboard: z6.boolean().optional(),
+  spotlight: z6.boolean().optional()
+});
+var hintComponent = z6.object({
+  kind: z6.literal("hint"),
+  id: z6.string(),
+  target: z6.string(),
+  selectorMeta: selectorMeta.optional(),
+  title: z6.string().optional(),
+  content: z6.string(),
+  position: z6.enum(["top-left", "top-right", "bottom-left", "bottom-right", "center"]).optional(),
+  tooltipPlacement: placement.optional(),
+  pulse: z6.boolean().optional(),
+  autoShow: z6.boolean().optional(),
+  persist: z6.boolean().optional(),
+  media: media.optional()
+});
+
+// ../recipe/src/recipe.ts
+import { z as z11 } from "zod";
+
+// ../recipe/src/scaffold.ts
+import { z as z7 } from "zod";
+var providerName = z7.enum(["LicenseProvider", "TourKitProvider"]);
+var scaffold = z7.object({
+  files: z7.array(z7.object({ path: z7.string(), purpose: z7.string().optional() })).default([]),
+  providerWrap: z7.object({
+    target: z7.literal("rootLayout"),
+    providers: z7.array(providerName).min(1)
+  }),
+  envVars: z7.array(z7.literal("TOUR_KIT_LICENSE_KEY")).default([]),
+  hooks: z7.array(z7.object({ ref: z7.string(), signature: z7.string() })).default([])
+});
+
+// ../recipe/src/schedule.ts
+import { z as z8 } from "zod";
+var dayOfWeek = z8.number().int().min(0).max(6);
+var scheduleDef = z8.object({
+  enabled: z8.boolean().optional(),
+  startAt: dateString.optional(),
+  endAt: dateString.optional(),
+  daysOfWeek: z8.array(dayOfWeek).optional(),
+  timeOfDay: z8.object({ start: timeString, end: timeString }).optional(),
+  useUserTimezone: z8.boolean().optional(),
+  timezone: z8.string().optional(),
+  recurring: z8.object({
+    type: z8.enum(["daily", "weekly", "monthly", "yearly"]),
+    interval: z8.number().int().optional(),
+    daysOfWeek: z8.array(dayOfWeek).optional(),
+    dayOfMonth: z8.number().int().min(1).max(31).optional(),
+    month: z8.number().int().min(1).max(12).optional(),
+    maxOccurrences: z8.number().int().optional(),
+    endDate: dateString.optional()
+  }).optional(),
+  blackouts: z8.array(
+    z8.object({
+      id: z8.string(),
+      start: dateString,
+      end: dateString,
+      reason: z8.string().optional()
+    })
+  ).optional()
+});
+
+// ../recipe/src/survey.ts
+import { z as z9 } from "zod";
+var ratingScale = z9.object({
+  min: z9.number(),
+  max: z9.number(),
+  step: z9.number().positive().optional(),
+  labels: z9.object({ min: z9.string().optional(), max: z9.string().optional() }).optional(),
+  style: z9.enum(["numeric", "stars", "emoji"]).optional()
+});
+var selectOption = z9.object({
+  value: z9.string(),
+  label: z9.string(),
+  disabled: z9.boolean().optional()
+});
+var skipLogicOps = [
+  "eq",
+  "neq",
+  "lt",
+  "lte",
+  "gt",
+  "gte",
+  "includes"
+];
+var skipLogicRule = z9.object({
+  questionId: z9.string(),
+  op: z9.enum(skipLogicOps),
+  value: z9.union([z9.string(), z9.number(), z9.boolean()]),
+  skipTo: z9.string()
+});
+var COMPARISON_OPS = /* @__PURE__ */ new Set(["lt", "lte", "gt", "gte"]);
+var surveyQuestion = z9.object({
+  id: z9.string().min(1),
+  type: z9.enum([
+    "rating",
+    "text",
+    "textarea",
+    "single-select",
+    "multi-select",
+    "boolean"
+  ]),
+  text: z9.string().min(1),
+  description: z9.string().optional(),
+  media: media.optional(),
+  required: z9.boolean().optional(),
+  placeholder: z9.string().optional(),
+  ratingScale: ratingScale.optional(),
+  preset: z9.enum(["thumbs", "stars"]).optional(),
+  options: z9.array(selectOption).min(1).optional(),
+  maxLength: z9.number().int().positive().optional(),
+  skipLogic: z9.array(skipLogicRule).optional()
+}).superRefine((q, ctx) => {
+  const isSelect = q.type === "single-select" || q.type === "multi-select";
+  const isText = q.type === "text" || q.type === "textarea";
+  if (q.options && !isSelect)
+    ctx.addIssue({
+      code: "custom",
+      path: ["options"],
+      message: "options are only valid on select questions"
+    });
+  if (isSelect && !q.options)
+    ctx.addIssue({
+      code: "custom",
+      path: ["options"],
+      message: "select questions require options"
+    });
+  if (q.ratingScale && q.type !== "rating")
+    ctx.addIssue({
+      code: "custom",
+      path: ["ratingScale"],
+      message: "ratingScale is only valid on rating questions"
+    });
+  if (q.preset && q.type !== "rating")
+    ctx.addIssue({
+      code: "custom",
+      path: ["preset"],
+      message: "preset is only valid on rating questions"
+    });
+  if (q.maxLength !== void 0 && !isText)
+    ctx.addIssue({
+      code: "custom",
+      path: ["maxLength"],
+      message: "maxLength is only valid on text/textarea questions"
+    });
+  if (q.placeholder !== void 0 && !isText)
+    ctx.addIssue({
+      code: "custom",
+      path: ["placeholder"],
+      message: "placeholder is only valid on text/textarea questions"
+    });
+  if (q.ratingScale && q.ratingScale.min >= q.ratingScale.max)
+    ctx.addIssue({
+      code: "custom",
+      path: ["ratingScale", "min"],
+      message: "ratingScale.min must be less than max"
+    });
+  q.skipLogic?.forEach((rule, i) => {
+    if (COMPARISON_OPS.has(rule.op) && typeof rule.value !== "number")
+      ctx.addIssue({
+        code: "custom",
+        path: ["skipLogic", i, "value"],
+        message: `op "${rule.op}" requires a numeric value`
+      });
+    if (rule.op === "includes" && typeof rule.value !== "string")
+      ctx.addIssue({
+        code: "custom",
+        path: ["skipLogic", i, "value"],
+        message: 'op "includes" requires a string value'
+      });
+  });
+});
+var surveyQuestions = z9.array(surveyQuestion).min(1).superRefine((qs, ctx) => {
+  const ids = qs.map((q) => q.id);
+  const seen = /* @__PURE__ */ new Set();
+  ids.forEach((id, i) => {
+    if (seen.has(id))
+      ctx.addIssue({
+        code: "custom",
+        path: [i, "id"],
+        message: `duplicate question id "${id}"`
+      });
+    seen.add(id);
+  });
+  qs.forEach((q, qi) => {
+    q.skipLogic?.forEach((rule, ri) => {
+      if (!seen.has(rule.questionId))
+        ctx.addIssue({
+          code: "custom",
+          path: [qi, "skipLogic", ri, "questionId"],
+          message: `unknown question "${rule.questionId}"`
+        });
+      if (!seen.has(rule.skipTo))
+        ctx.addIssue({
+          code: "custom",
+          path: [qi, "skipLogic", ri, "skipTo"],
+          message: `unknown question "${rule.skipTo}"`
+        });
+      else if (ids.indexOf(rule.skipTo) <= qi)
+        ctx.addIssue({
+          code: "custom",
+          path: [qi, "skipLogic", ri, "skipTo"],
+          message: "skipTo must reference a LATER question (loop guard)"
+        });
+    });
+  });
+});
+var frequencyRule = z9.union([
+  z9.enum(["once", "session", "always"]),
+  z9.object({ type: z9.literal("times"), count: z9.number().int().positive() }),
+  z9.object({ type: z9.literal("interval"), days: z9.number().positive() })
+]);
+var modalOptions = z9.object({
+  size: z9.enum(["sm", "md", "lg"]).optional(),
+  closeOnOverlayClick: z9.boolean().optional(),
+  closeOnEscape: z9.boolean().optional(),
+  showCloseButton: z9.boolean().optional()
+});
+var slideoutOptions = z9.object({
+  position: z9.enum(["left", "right"]).optional(),
+  size: z9.enum(["sm", "md", "lg"]).optional(),
+  closeOnOverlayClick: z9.boolean().optional(),
+  closeOnEscape: z9.boolean().optional(),
+  showCloseButton: z9.boolean().optional()
+});
+var bannerOptions = z9.object({
+  position: z9.enum(["top", "bottom"]).optional(),
+  sticky: z9.boolean().optional(),
+  dismissable: z9.boolean().optional(),
+  intent: z9.enum(["info", "feedback"]).optional()
+});
+var popoverOptions = z9.object({
+  position: z9.enum(["bottom-right", "bottom-left", "top-right", "top-left"]).optional(),
+  offset: z9.number().optional(),
+  showCloseButton: z9.boolean().optional()
+});
+var surveyComponent = z9.object({
+  kind: z9.literal("survey"),
+  id: z9.string(),
+  type: z9.enum(["nps", "csat", "ces", "custom"]),
+  displayMode: z9.enum(["popover", "modal", "slideout", "banner", "inline"]),
+  priority: z9.enum(["critical", "high", "normal", "low"]).optional(),
+  title: z9.string().optional(),
+  description: z9.string().optional(),
+  questions: surveyQuestions,
+  frequency: frequencyRule.optional(),
+  schedule: z9.string().optional(),
+  globalCooldownDays: z9.number().nonnegative().optional(),
+  samplingRate: z9.number().min(0).max(1).optional(),
+  maxSnoozeCount: z9.number().int().nonnegative().optional(),
+  snoozeDelayDays: z9.number().nonnegative().optional(),
+  maxPerSession: z9.number().int().positive().optional(),
+  modalOptions: modalOptions.optional(),
+  slideoutOptions: slideoutOptions.optional(),
+  bannerOptions: bannerOptions.optional(),
+  popoverOptions: popoverOptions.optional()
+});
+
+// ../recipe/src/theme.ts
+import { z as z10 } from "zod";
+var themeTokenKey = z10.string().regex(
+  /^--[a-z][a-z0-9-]{0,30}$/,
+  "theme token keys must be --kebab-case CSS custom properties"
+);
+var themeTokenValue = z10.string().regex(
+  /^[a-zA-Z0-9#.,()%\s/-]{1,64}$/,
+  "theme token values may only contain color/length characters (1\u201364 chars)"
+);
+var themeTokens = z10.record(themeTokenKey, themeTokenValue);
+var themeMatcher = z10.object({ kind: z10.literal("system") });
+var themeVariation = z10.object({
+  id: z10.string().min(1),
+  when: themeMatcher,
+  theme: themeTokens
+});
+var recipeTheme = z10.object({
+  variations: z10.array(themeVariation).length(1)
+});
+var TOKEN_BRIDGE = {
+  "--primary": "--tour-primary",
+  "--primary-foreground": "--tour-primary-fg",
+  "--popover": "--tour-card-bg",
+  "--popover-foreground": "--tour-card-fg",
+  "--muted-foreground": "--tour-muted-fg",
+  "--border": "--tour-card-border",
+  "--ring": "--tour-ring",
+  "--radius": "--tour-card-radius"
+};
+var SCOPED_SELECTORS = ["[data-tour-step]"];
+
+// ../recipe/src/recipe.ts
+var SUPPORTED_DEPS = {
+  "@tour-kit/core": "1.0.6",
+  "@tour-kit/react": "1.0.6",
+  "@tour-kit/hints": "1.0.6",
+  "@tour-kit/media": "0.13.2",
+  "@tour-kit/checklists": "0.13.9",
+  "@tour-kit/announcements": "4.1.6",
+  "@tour-kit/scheduling": "0.11.9",
+  "@tour-kit/surveys": "3.0.9",
+  "@tour-kit/license": "1.3.5"
+};
+var RUNTIME_PEERS = {
+  "@tour-kit/react": {
+    // 0.11.9 = the exact analytics peer of react/hints/checklists/
+    // announcements/scheduling at the pinned versions (the 0.11.9 train —
+    // see the SUPPORTED_DEPS coherence note). surveys@3.0.9 has no
+    // analytics peer of its own.
+    "@tour-kit/analytics": "0.11.9",
+    // media@0.13.x still ranges `^3.5.0` — the Phase 25 QA-proven pin stands.
+    "@lottiefiles/react-lottie-player": "3.5.4"
+  }
+};
+function runtimePeerSpecs(packages) {
+  const specs = /* @__PURE__ */ new Set();
+  for (const pkg of packages) {
+    const peers = RUNTIME_PEERS[pkg];
+    if (!peers) continue;
+    for (const [name, version] of Object.entries(peers))
+      specs.add(`${name}@${version}`);
+  }
+  return [...specs].sort();
+}
+var PRO_PACKAGES = [
+  "@tour-kit/media",
+  "@tour-kit/announcements",
+  "@tour-kit/checklists",
+  "@tour-kit/license",
+  "@tour-kit/scheduling",
+  "@tour-kit/surveys"
+];
+var tkPackage = z11.enum(
+  Object.keys(SUPPORTED_DEPS)
+);
+var recipeComponent = z11.discriminatedUnion("kind", [
+  tourComponent,
+  hintComponent,
+  checklistComponent,
+  announcementComponent,
+  surveyComponent
+]);
+var isSupportedPackage = (p) => p in SUPPORTED_DEPS;
+var usesMedia = (c) => {
+  switch (c.kind) {
+    case "tour":
+      return c.steps.some((s) => s.kind === "visible" && s.media !== void 0);
+    case "checklist":
+      return c.tasks.some((t) => t.media !== void 0);
+    case "survey":
+      return c.questions.some((q) => q.media !== void 0);
+    case "hint":
+    case "announcement":
+      return c.media !== void 0;
+  }
+};
+var requiredPackages = (c) => {
+  const req = /* @__PURE__ */ new Set(["@tour-kit/react"]);
+  if (c.kind === "tour") req.add("@tour-kit/core");
+  else if (c.kind === "hint") req.add("@tour-kit/hints");
+  else if (c.kind === "checklist") req.add("@tour-kit/checklists");
+  else if (c.kind === "announcement") req.add("@tour-kit/announcements");
+  else if (c.kind === "survey") req.add("@tour-kit/surveys");
+  if (usesMedia(c)) req.add("@tour-kit/media");
+  if ((c.kind === "announcement" || c.kind === "survey") && c.schedule)
+    req.add("@tour-kit/scheduling");
+  return [...req];
+};
+var recipeSchemaV1 = z11.object({
+  $schema: z11.string().optional(),
+  schemaVersion: z11.literal(1),
+  id: recipeId,
+  version: semver,
+  name: z11.string().min(1),
+  tier: z11.enum(["free", "pro"]),
+  packages: z11.array(tkPackage).min(1),
+  components: z11.array(recipeComponent).min(1),
+  schedules: z11.record(z11.string(), scheduleDef).optional(),
+  // Recipe-global theme (Phase 32): one base ThemeVariation projected from
+  // @tour-kit/react — see ./theme for the executable-subset rules.
+  theme: recipeTheme.optional(),
+  scaffold,
+  deps: z11.record(z11.string(), z11.string()),
+  meta: z11.object({ createdAt: z11.iso.datetime(), studioVersion: z11.string() })
+}).superRefine((r, ctx) => {
+  const derived = r.packages.some(
+    (p) => PRO_PACKAGES.includes(p)
+  ) ? "pro" : "free";
+  if (r.tier !== derived)
+    ctx.addIssue({
+      code: "custom",
+      path: ["tier"],
+      message: `tier must be "${derived}"`
+    });
+  for (const p of r.packages) {
+    const pinned = r.deps[p];
+    if (pinned !== SUPPORTED_DEPS[p])
+      ctx.addIssue({
+        code: "custom",
+        path: ["deps", p],
+        message: `package dep must be pinned to ${SUPPORTED_DEPS[p]}`
+      });
+  }
+  for (const p of Object.keys(r.deps)) {
+    if (!isSupportedPackage(p) || !r.packages.includes(p))
+      ctx.addIssue({
+        code: "custom",
+        path: ["deps", p],
+        message: "deps may only contain selected, supported @tour-kit packages"
+      });
+  }
+  const providers = r.scaffold.providerWrap.providers;
+  if (derived === "pro" && (!r.packages.includes("@tour-kit/license") || providers[0] !== "LicenseProvider" || providers[1] !== "TourKitProvider" || !r.scaffold.envVars.includes("TOUR_KIT_LICENSE_KEY")))
+    ctx.addIssue({
+      code: "custom",
+      path: ["scaffold"],
+      message: "pro recipe must install @tour-kit/license, wrap both providers, and expose TOUR_KIT_LICENSE_KEY"
+    });
+  if (derived === "free" && !providers.includes("TourKitProvider"))
+    ctx.addIssue({
+      code: "custom",
+      path: ["scaffold", "providerWrap"],
+      message: "free recipe must inject TourKitProvider"
+    });
+  for (const c of r.components)
+    if ((c.kind === "announcement" || c.kind === "survey") && c.schedule && !r.schedules?.[c.schedule])
+      ctx.addIssue({
+        code: "custom",
+        path: ["components"],
+        message: `unknown schedule "${c.schedule}"`
+      });
+  const selected = new Set(r.packages);
+  r.components.forEach((c, i) => {
+    const missing = requiredPackages(c).filter((p) => !selected.has(p));
+    if (missing.length > 0)
+      ctx.addIssue({
+        code: "custom",
+        path: ["components", i],
+        message: `"${c.kind}" component requires package(s) not in the recipe: ${missing.join(", ")}`
+      });
+  });
+  if (r.schedules && Object.keys(r.schedules).length > 0 && !selected.has("@tour-kit/scheduling"))
+    ctx.addIssue({
+      code: "custom",
+      path: ["schedules"],
+      message: "schedules require @tour-kit/scheduling"
+    });
+});
+
+// src/commands/add.ts
+import { defineCommand } from "citty";
+import { consola as consola3 } from "consola";
+import { execa } from "execa";
+
+// src/lib/detect.ts
+import { existsSync } from "fs";
+import { join } from "path";
+import { readPackageJSON } from "pkg-types";
+
+// src/lib/result.ts
+import { consola } from "consola";
+import { ZodError } from "zod";
+var CliError = class extends Error {
+  constructor(message, exitCode) {
+    super(message);
+    this.exitCode = exitCode;
+    this.name = "CliError";
+  }
+  exitCode;
+};
+function emitResult(result, json) {
+  if (json) {
+    process.stdout.write(JSON.stringify(result));
+    return;
+  }
+  consola.box(
+    [
+      result.ok ? "Plan ready" : "Plan failed",
+      `framework:        ${result.framework ?? "unknown (detection lands in a later phase)"}`,
+      `packages:         ${result.packages.join(", ") || "(none)"}`,
+      `runtime peers:    ${result.runtimePeers.join(", ") || "(none)"}`,
+      `would write:      ${result.filesWritten.join(", ") || "(none)"}`,
+      `provider patched: ${result.providerPatched}`
+    ].join("\n")
+  );
+}
+function toExitCode(err) {
+  if (err instanceof CliError)
+    return { code: err.exitCode, message: err.message };
+  if (err instanceof ZodError) return { code: 2, message: "invalid recipe" };
+  return { code: 1, message: err instanceof Error ? err.message : String(err) };
+}
+async function runOrExit(fn) {
+  try {
+    await fn();
+  } catch (err) {
+    const { code, message } = toExitCode(err);
+    consola.error(message);
+    process.exit(code);
+  }
+}
+
+// src/lib/detect.ts
+var LICENSE_ENV = {
+  "next-app": {
+    name: "NEXT_PUBLIC_TOUR_KIT_LICENSE_KEY",
+    expression: "process.env.NEXT_PUBLIC_TOUR_KIT_LICENSE_KEY"
+  },
+  "next-pages": {
+    name: "NEXT_PUBLIC_TOUR_KIT_LICENSE_KEY",
+    expression: "process.env.NEXT_PUBLIC_TOUR_KIT_LICENSE_KEY"
+  },
+  "vite-react": {
+    name: "VITE_TOUR_KIT_LICENSE_KEY",
+    expression: "import.meta.env.VITE_TOUR_KIT_LICENSE_KEY"
+  },
+  remix: {
+    name: "PUBLIC_TOUR_KIT_LICENSE_KEY",
+    expression: "window.ENV?.PUBLIC_TOUR_KIT_LICENSE_KEY"
+  },
+  astro: {
+    name: "PUBLIC_TOUR_KIT_LICENSE_KEY",
+    expression: "import.meta.env.PUBLIC_TOUR_KIT_LICENSE_KEY"
+  },
+  cra: {
+    name: "REACT_APP_TOUR_KIT_LICENSE_KEY",
+    expression: "process.env.REACT_APP_TOUR_KIT_LICENSE_KEY"
+  }
+};
+var ENTRY = {
+  "next-app": "app/layout.tsx",
+  "next-pages": "pages/_app.tsx",
+  "vite-react": "src/main.tsx",
+  remix: "app/root.tsx",
+  astro: "src/layouts/Layout.astro",
+  cra: "src/index.tsx"
+};
+async function detectProject(cwd) {
+  const pkg = await readPackageJSON(cwd);
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+  const packageManager = existsSync(
+    join(cwd, "pnpm-lock.yaml")
+  ) ? "pnpm" : existsSync(join(cwd, "bun.lock")) || existsSync(join(cwd, "bun.lockb")) ? "bun" : existsSync(join(cwd, "yarn.lock")) ? "yarn" : "npm";
+  const framework = deps.next && existsSync(join(cwd, "app")) ? "next-app" : deps.next ? "next-pages" : deps["@remix-run/react"] ? "remix" : deps.astro ? "astro" : deps.vite ? "vite-react" : deps["react-scripts"] ? "cra" : null;
+  if (!framework) throw new CliError("unsupported framework", 2);
+  return {
+    framework,
+    packageManager,
+    entryFile: join(cwd, ENTRY[framework]),
+    formatter: existsSync(join(cwd, "biome.json")) ? "biome" : existsSync(join(cwd, ".prettierrc")) ? "prettier" : null,
+    typescript: existsSync(join(cwd, "tsconfig.json")),
+    licenseEnv: LICENSE_ENV[framework]
+  };
+}
+
+// src/lib/header.ts
+function header(id, version) {
+  return `// Generated by User Tour Kit Studio \xB7 recipe: ${id}@${version}
+// Edit freely. Sync with: npx @tour-kit/studio pull ${id}`;
+}
+
+// src/lib/expand.ts
+var pad = (level) => "  ".repeat(level);
+var isIdentifier = (k) => /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(k);
+var key = (k) => isIdentifier(k) ? k : str(k);
+function str(s) {
+  if (s.includes('"') && !s.includes("'"))
+    return `'${s.replace(/\\/g, "\\\\").replace(/\n/g, "\\n")}'`;
+  return JSON.stringify(s);
+}
+var isPrimitive = (v) => v === null || typeof v === "string" || typeof v === "number" || typeof v === "boolean";
+var RawCode = class {
+  constructor(code) {
+    this.code = code;
+  }
+  code;
+};
+function serialize(value, level) {
+  if (value === null) return "null";
+  if (value instanceof RawCode) return value.code;
+  if (typeof value === "string") return str(value);
+  if (typeof value === "number" || typeof value === "boolean")
+    return String(value);
+  if (Array.isArray(value)) {
+    if (value.length === 0) return "[]";
+    if (value.every(isPrimitive))
+      return `[${value.map((v) => serialize(v, level)).join(", ")}]`;
+    const items = value.map((v) => `${pad(level + 1)}${serialize(v, level + 1)}`).join(",\n");
+    return `[
+${items}
+${pad(level)}]`;
+  }
+  if (typeof value === "object") {
+    const entries = Object.entries(value).filter(([, v]) => v !== void 0).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+    if (entries.length === 0) return "{}";
+    const body = entries.map(([k, v]) => `${pad(level + 1)}${key(k)}: ${serialize(v, level + 1)}`).join(",\n");
+    return `{
+${body}
+${pad(level)}}`;
+  }
+  throw new CliError(
+    `expand: cannot serialize value of type ${typeof value}`,
+    2
+  );
+}
+var sanitize = (s) => s.replace(/[^A-Za-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+var hookName = (ref) => `hook_${sanitize(ref)}`;
+function wrap(kind, id, cfg, note = "", type) {
+  const decl = `${kind}_${sanitize(id)}${type ? `: ${type}` : ""}`;
+  return `// ${kind}: ${id}${note}
+export const ${decl} = ${serialize(cfg, 0)};`;
+}
+var ANNOUNCEMENT_COMPONENT = {
+  modal: "AnnouncementModal",
+  slideout: "AnnouncementSlideout",
+  banner: "AnnouncementBanner",
+  toast: "AnnouncementToast",
+  spotlight: "AnnouncementSpotlight"
+};
+var SURVEY_COMPONENT = {
+  popover: "SurveyPopover",
+  modal: "SurveyModal",
+  slideout: "SurveySlideout",
+  banner: "SurveyBanner",
+  inline: "SurveyInline"
+};
+function conditionSource(rule) {
+  const { op, value } = rule;
+  switch (op) {
+    case "eq":
+    case "neq": {
+      const cmp2 = typeof value === "number" ? `Number(answer) === ${value}` : typeof value === "string" ? `String(answer) === ${str(value)}` : `answer === ${value}`;
+      return op === "neq" ? `(answer) => !(${cmp2})` : `(answer) => ${cmp2}`;
+    }
+    case "lt":
+      return `(answer) => Number(answer) < ${Number(value)}`;
+    case "lte":
+      return `(answer) => Number(answer) <= ${Number(value)}`;
+    case "gt":
+      return `(answer) => Number(answer) > ${Number(value)}`;
+    case "gte":
+      return `(answer) => Number(answer) >= ${Number(value)}`;
+    case "includes":
+      return `(answer) => Array.isArray(answer) && answer.includes(${str(String(value))})`;
+  }
+}
+function imports(recipe) {
+  const kinds = new Set(recipe.components.map((c) => c.kind));
+  const value = [];
+  const types = [];
+  if (kinds.has("survey"))
+    value.push(`import { useEffect, useRef } from "react";`);
+  const reactNames = [];
+  if (recipe.theme) reactNames.push("ThemeProvider");
+  if (kinds.has("tour")) reactNames.push("Tour", "TourStep");
+  if (reactNames.length > 0)
+    value.push(
+      `import { ${reactNames.sort().join(", ")} } from "@tour-kit/react";`
+    );
+  if (kinds.has("hint"))
+    value.push(`import { Hint, HintsProvider } from "@tour-kit/hints";`);
+  if (kinds.has("checklist")) {
+    value.push(
+      `import { Checklist, ChecklistProvider } from "@tour-kit/checklists";`
+    );
+    types.push(`import type { ChecklistConfig } from "@tour-kit/checklists";`);
+  }
+  if (kinds.has("announcement")) {
+    const variants = [
+      ...new Set(
+        recipe.components.filter((c) => c.kind === "announcement").map((c) => ANNOUNCEMENT_COMPONENT[c.variant])
+      )
+    ];
+    const named = ["AnnouncementsProvider", ...variants].sort();
+    value.push(
+      `import { ${named.join(", ")} } from "@tour-kit/announcements";`
+    );
+    types.push(
+      `import type { AnnouncementConfig } from "@tour-kit/announcements";`
+    );
+  }
+  if (kinds.has("survey")) {
+    const displays = [
+      ...new Set(
+        recipe.components.filter((c) => c.kind === "survey").map((c) => SURVEY_COMPONENT[c.displayMode])
+      )
+    ];
+    const named = [
+      "QuestionBoolean",
+      "QuestionMedia",
+      "QuestionRating",
+      "QuestionSelect",
+      "QuestionText",
+      "SurveyProgress",
+      "SurveysProvider",
+      "useSurvey",
+      ...displays
+    ].sort();
+    value.push(`import { ${named.join(", ")} } from "@tour-kit/surveys";`);
+    types.push(
+      `import type { AnswerValue, SurveyConfig } from "@tour-kit/surveys";`
+    );
+  }
+  if (recipe.theme)
+    types.push(`import type { ThemeVariation } from "@tour-kit/react";`);
+  return [...value, ...types].join("\n");
+}
+var cmp = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+var cssBlock = (sel, decls) => decls.length === 0 ? "" : `${sel} { ${decls.map(([k, v]) => `${k}: ${v};`).join(" ")} }`;
+function themeCssFor(tokens) {
+  const entries = Object.entries(tokens);
+  const bridged = entries.flatMap(([k, v]) => {
+    const target = TOKEN_BRIDGE[k];
+    return target === void 0 ? [] : [[target, v]];
+  }).sort(([a], [b]) => cmp(a, b));
+  const all = [...entries].sort(([a], [b]) => cmp(a, b));
+  return [
+    cssBlock(":root", bridged),
+    ...SCOPED_SELECTORS.map((sel) => cssBlock(sel, all))
+  ].filter((b) => b !== "").join("\n");
+}
+function emitTheme(theme) {
+  const css = themeCssFor(theme.variations[0]?.theme ?? {});
+  return [
+    "// theme: recipe-global ThemeProvider variations + the portal-bridging <style> css",
+    `export const THEME_VARIATIONS: ThemeVariation[] = ${serialize(theme.variations, 0)};`,
+    `export const THEME_CSS = ${str(css)};`
+  ].join("\n");
+}
+var jsxAttr = (name, value) => ` ${name}={${serialize(value, 0)}}`;
+var STEP_FIELDS = [
+  "target",
+  "content",
+  "title",
+  "placement",
+  "showNavigation",
+  "showClose",
+  "showProgress"
+];
+function emitTourStep(c, s) {
+  const attrs = STEP_FIELDS.filter((k) => s[k] !== void 0).map((k) => jsxAttr(k, s[k])).join("");
+  return `        <TourStep key={${serialize(`${c.id}:${s.id}`, 0)}} id={${serialize(s.id, 0)}}${attrs} />`;
+}
+var TOUR_FIELDS = ["autoStart", "startAt"];
+function emitTour(c) {
+  const open = TOUR_FIELDS.filter((k) => c[k] !== void 0).map((k) => jsxAttr(k, c[k])).join("");
+  const steps = c.steps.filter((s) => s.kind === "visible").map((s) => emitTourStep(c, s)).join("\n");
+  return `      <Tour key={${serialize(c.id, 0)}} id={${serialize(c.id, 0)}}${open}>
+${steps}
+      </Tour>`;
+}
+var HINT_FIELDS = [
+  "target",
+  "content",
+  "title",
+  "position",
+  "tooltipPlacement",
+  "pulse",
+  "autoShow",
+  "persist"
+];
+function emitHint(c) {
+  const attrs = HINT_FIELDS.filter((k) => c[k] !== void 0).map((k) => jsxAttr(k, c[k])).join("");
+  return `      <Hint key={${serialize(c.id, 0)}} id={${serialize(c.id, 0)}}${attrs} />`;
+}
+function emitChecklistEl(c) {
+  return `      <Checklist key={${serialize(c.id, 0)}} checklistId={${serialize(c.id, 0)}} showProgress />`;
+}
+function emitAnnouncementEl(c) {
+  const Comp = ANNOUNCEMENT_COMPONENT[c.variant];
+  return `      <${Comp} key={${serialize(c.id, 0)}} id={${serialize(c.id, 0)}} useConfig />`;
+}
+function emitSurveyEl(c) {
+  const Comp = SURVEY_COMPONENT[c.displayMode];
+  const id = serialize(c.id, 0);
+  const lines = [
+    `      <SurveyAutoShow key={${serialize(`${c.id}:auto-show`, 0)}} surveyId={${id}} />`
+  ];
+  if (c.displayMode === "popover") {
+    lines.push(
+      `      {/* TODO: move the data-survey-popover-anchor attribute onto the element this survey should attach to */}`,
+      `      <span data-survey-popover-anchor={${id}}>Feedback</span>`
+    );
+  }
+  if (c.displayMode === "inline")
+    lines.push(
+      `      {/* SurveyInline renders in-flow exactly where it is mounted \u2014 move it where the survey belongs */}`
+    );
+  lines.push(
+    `      <${Comp} key={${id}} surveyId={${id}}>
+        <SurveyBody surveyId={${id}} />
+      </${Comp}>`
+  );
+  return lines.join("\n");
+}
+var emitElement = (c) => {
+  switch (c.kind) {
+    case "tour":
+      return emitTour(c);
+    case "hint":
+      return emitHint(c);
+    case "checklist":
+      return emitChecklistEl(c);
+    case "announcement":
+      return emitAnnouncementEl(c);
+    case "survey":
+      return emitSurveyEl(c);
+  }
+};
+var indentBlock = (block, levels) => levels <= 0 ? block : block.split("\n").map((l) => l === "" ? l : `${pad(levels)}${l}`).join("\n");
+function emitMount(recipe) {
+  const inner = recipe.components.map(emitElement).join("\n");
+  const checklistConsts = recipe.components.filter((c) => c.kind === "checklist").map((c) => `checklist_${sanitize(c.id)}`);
+  const announcementConsts = recipe.components.filter((c) => c.kind === "announcement").map((c) => `announcement_${sanitize(c.id)}`);
+  const surveyConsts = recipe.components.filter((c) => c.kind === "survey").map((c) => `survey_${sanitize(c.id)}`);
+  const providers = [];
+  if (recipe.components.some((c) => c.kind === "hint"))
+    providers.push({ open: "<HintsProvider>", close: "</HintsProvider>" });
+  if (checklistConsts.length > 0)
+    providers.push({
+      open: `<ChecklistProvider checklists={[${checklistConsts.join(", ")}]} persistence={{ enabled: false }}>`,
+      close: "</ChecklistProvider>"
+    });
+  if (announcementConsts.length > 0)
+    providers.push({
+      open: `<AnnouncementsProvider announcements={[${announcementConsts.join(", ")}]}>`,
+      close: "</AnnouncementsProvider>"
+    });
+  if (surveyConsts.length > 0)
+    providers.push({
+      open: `<SurveysProvider surveys={[${surveyConsts.join(", ")}]}>`,
+      close: "</SurveysProvider>"
+    });
+  let body;
+  if (providers.length === 0) {
+    body = `    <>
+${inner}
+    </>`;
+  } else {
+    const elements = indentBlock(inner, providers.length - 1);
+    const opens = providers.map((p, i) => `${pad(2 + i)}${p.open}`).join("\n");
+    const closes = providers.map((p, i) => `${pad(2 + i)}${p.close}`).reverse().join("\n");
+    body = `${opens}
+${elements}
+${closes}`;
+  }
+  if (recipe.theme) {
+    body = `${pad(2)}<ThemeProvider variations={THEME_VARIATIONS}>
+${pad(3)}<style>{THEME_CSS}</style>
+${indentBlock(body, 1)}
+${pad(2)}</ThemeProvider>`;
+  }
+  return `export default function RecipeMount() {
+  return (
+${body}
+  );
+}`;
+}
+var STRIP = /* @__PURE__ */ new Set(["selectorMeta"]);
+function clean(value) {
+  if (value instanceof RawCode) return value;
+  if (Array.isArray(value)) return value.map(clean);
+  if (value !== null && typeof value === "object")
+    return Object.fromEntries(
+      Object.entries(value).filter(([k]) => !STRIP.has(k)).map(([k, v]) => [k, clean(v)])
+    );
+  return value;
+}
+function emitComponent(c, r) {
+  switch (c.kind) {
+    case "tour":
+    case "hint": {
+      const { kind, ...rest } = c;
+      return wrap(kind, c.id, clean(rest));
+    }
+    case "checklist": {
+      const { kind, ...rest } = c;
+      return wrap(kind, c.id, clean(rest), "", "ChecklistConfig");
+    }
+    case "announcement": {
+      const { kind, schedule, ...rest } = c;
+      const cfg = schedule ? { ...rest, schedule: r.schedules?.[schedule] } : rest;
+      return wrap(
+        kind,
+        c.id,
+        clean(cfg),
+        schedule ? ` (schedule: ${schedule})` : "",
+        "AnnouncementConfig"
+      );
+    }
+    case "survey": {
+      const { kind, schedule, questions, ...rest } = c;
+      const sdkQuestions = questions.map((q) => {
+        const { skipLogic, ...qRest } = q;
+        return skipLogic ? {
+          ...qRest,
+          skipLogic: skipLogic.map((rule) => ({
+            questionId: rule.questionId,
+            condition: new RawCode(conditionSource(rule)),
+            skipTo: rule.skipTo
+          }))
+        } : qRest;
+      });
+      const cfg = {
+        ...rest,
+        questions: sdkQuestions,
+        ...schedule ? { schedule: r.schedules?.[schedule] } : {}
+      };
+      const hasSkipLogic = questions.some(
+        (q) => (q.skipLogic?.length ?? 0) > 0
+      );
+      const note = `${schedule ? ` (schedule: ${schedule})` : ""}${hasSkipLogic ? "\n// skip-logic is EVALUATED by the generated SurveyBody below (resolveSkipTarget,\n// applied on Next): @tour-kit/surveys 3.0.9 types SkipLogic but does not evaluate it\n// itself \u2014 the config below is the published contract, this file is the executor." : ""}`;
+      return wrap(kind, c.id, clean(cfg), note, "SurveyConfig");
+    }
+    default: {
+      const _never = c;
+      throw new CliError(
+        `expand: unhandled component kind ${JSON.stringify(_never)}`,
+        2
+      );
+    }
+  }
+}
+var SURVEY_HELPERS = `// Where Next lands from question \`current\`: the first matching rule wins (in
+// authored array order); an unanswered tested question never matches; no match
+// advances one step. Skip targets are always later than the carrying question
+// (the Studio validates this), so the seek is forward-only. Back is
+// deliberately linear \u2014 after a skip it revisits the skipped question.
+function resolveSkipTarget(
+  questions: SurveyConfig["questions"],
+  current: number,
+  responses: ReadonlyMap<string, AnswerValue>,
+): number {
+  const rules = questions[current]?.skipLogic ?? [];
+  const hit = rules.find((rule) => {
+    const answer = responses.get(rule.questionId);
+    return answer !== undefined && rule.condition(answer);
+  });
+  if (!hit) return current + 1;
+  const target = questions.findIndex((q) => q.id === hit.skipTo);
+  return target > current ? target : current + 1;
+}
+
+// Renders the active question of a survey: the Survey* display components are
+// chrome-only wrappers, so the question body must be composed explicitly.
+function SurveyBody({ surveyId }: { surveyId: string }) {
+  const survey = useSurvey(surveyId);
+  const config = survey.config;
+  const state = survey.state;
+  const question = config?.questions[state?.currentStep ?? 0];
+  if (!config || !state || !question) return null;
+  const label = typeof question.text === "string" ? question.text : question.id;
+  const answer = state.responses.get(question.id);
+  const isLast = state.currentStep >= config.questions.length - 1;
+  // The SDK advances one question per nextQuestion() call (no goTo), so Next
+  // seeks the skip target by stepping forward to it.
+  const advance = () => {
+    const target = resolveSkipTarget(
+      config.questions,
+      state.currentStep,
+      state.responses,
+    );
+    for (let k = state.currentStep; k < target; k++) survey.nextQuestion();
+  };
+  return (
+    <div className="flex flex-col gap-4">
+      <SurveyProgress current={state.currentStep + 1} total={config.questions.length} />
+      <QuestionMedia question={question} />
+      {/* The Question* controls carry the prompt as aria-label only \u2014 render it
+          visibly here (the SDK's turnkey modals do the same). */}
+      <p className="text-sm font-medium">{label}</p>
+      {typeof question.description === "string" && (
+        <p className="text-sm text-muted-foreground">{question.description}</p>
+      )}
+      {question.type === "rating" && (
+        <QuestionRating
+          id={question.id}
+          label={label}
+          // ratingScale wins over preset/min/max/style defaults and carries
+          // step (QuestionRatingProps has no step prop; the 3.0.9 renderer
+          // does not consume step yet \u2014 forward-compat).
+          ratingScale={question.ratingScale}
+          preset={question.preset}
+          value={typeof answer === "number" ? answer : null}
+          onChange={(v) => survey.answer(question.id, v)}
+          isRequired={question.required}
+        />
+      )}
+      {(question.type === "text" || question.type === "textarea") && (
+        <QuestionText
+          id={question.id}
+          mode={question.type}
+          label={label}
+          placeholder={typeof question.placeholder === "string" ? question.placeholder : undefined}
+          maxLength={question.maxLength}
+          value={typeof answer === "string" ? answer : ""}
+          onChange={(v) => survey.answer(question.id, v)}
+          isRequired={question.required}
+        />
+      )}
+      {(question.type === "single-select" || question.type === "multi-select") && (
+        <QuestionSelect
+          id={question.id}
+          mode={question.type === "multi-select" ? "multi" : "single"}
+          label={label}
+          options={question.options ?? []}
+          value={typeof answer === "string" || Array.isArray(answer) ? answer : undefined}
+          onChange={(v) => survey.answer(question.id, v)}
+          isRequired={question.required}
+        />
+      )}
+      {question.type === "boolean" && (
+        <QuestionBoolean
+          id={question.id}
+          label={label}
+          value={typeof answer === "boolean" ? answer : null}
+          onChange={(v) => survey.answer(question.id, v)}
+          isRequired={question.required}
+        />
+      )}
+      <div className="flex justify-end gap-2">
+        {state.currentStep > 0 && (
+          <button type="button" onClick={() => survey.prevQuestion()}>
+            Back
+          </button>
+        )}
+        <button
+          type="button"
+          onClick={() => (isLast ? survey.complete() : advance())}
+        >
+          {isLast ? "Done" : "Next"}
+        </button>
+      </div>
+    </div>
+  );
+}
+
+// Registration alone leaves a survey hidden \u2014 show it ONCE when the provider's
+// gates (schedule, frequency, fatigue, sampling) allow.
+function SurveyAutoShow({ surveyId }: { surveyId: string }) {
+  const survey = useSurvey(surveyId);
+  const shownRef = useRef(false);
+  useEffect(() => {
+    if (survey.canShow && !shownRef.current) {
+      shownRef.current = true;
+      survey.show();
+    }
+  }, [survey]);
+  return null;
+}`;
+function emitHooks(recipe) {
+  const stubs = recipe.scaffold.hooks.map(
+    (h) => `// ref: ${h.ref}
+export const ${hookName(h.ref)}: ${h.signature} = () => {
+  throw new Error("TODO: implement hook for ${h.ref}");
+};`
+  ).join("\n\n");
+  return `${header(recipe.id, recipe.version)}
+
+${stubs}
+`;
+}
+function expand(recipe) {
+  const body = recipe.components.map((c) => emitComponent(c, recipe)).join("\n\n");
+  const helpers = recipe.components.some((c) => c.kind === "survey") ? `
+
+${SURVEY_HELPERS}` : "";
+  const themeConsts = recipe.theme ? `
+
+${emitTheme(recipe.theme)}` : "";
+  const contents = `${header(recipe.id, recipe.version)}
+"use client";
+${imports(recipe)}
+
+${body}${helpers}${themeConsts}
+
+${emitMount(recipe)}
+`;
+  const files = [{ path: `tours/${recipe.id}.tsx`, contents }];
+  if (recipe.scaffold.hooks.length > 0)
+    files.push({
+      path: `tours/${recipe.id}.hooks.ts`,
+      contents: emitHooks(recipe)
+    });
+  return files;
+}
+
+// src/lib/fetch-recipe.ts
+import { z as z12 } from "zod";
+var SUPPORTED = 1;
+var schemaVersionProbe = z12.object({
+  schemaVersion: z12.number().int().optional()
+});
+async function fetchRecipe(id, base = "https://usertourkit.com/builder") {
+  const res = await fetch(`${base}/api/recipes/${id}`);
+  if (res.status === 404) throw new CliError("unknown recipe", 1);
+  const json = await res.json();
+  const probe = schemaVersionProbe.safeParse(json);
+  if (probe.success && probe.data.schemaVersion && probe.data.schemaVersion > SUPPORTED)
+    throw new CliError(
+      "recipe schemaVersion newer than this CLI \u2014 upgrade @tour-kit/studio",
+      2
+    );
+  return recipeSchemaV1.parse(json);
+}
+
+// src/lib/patch.ts
+import { execFile } from "child_process";
+import { promisify } from "util";
+import { consola as consola2 } from "consola";
+import { IndentationText, Node, Project, QuoteKind } from "ts-morph";
+var execFileAsync = promisify(execFile);
+function providerStack(tier, envExpr, module) {
+  const tour = {
+    name: "TourKitProvider",
+    module,
+    open: "<TourKitProvider>",
+    close: "</TourKitProvider>"
+  };
+  if (tier === "free") return [tour];
+  return [
+    {
+      name: "LicenseProvider",
+      module,
+      open: `<LicenseProvider licenseKey={${envExpr} ?? ""}>`,
+      close: "</LicenseProvider>"
+    },
+    tour
+  ];
+}
+var wrap2 = (providers, inner) => providers.reduceRight((acc, p) => `${p.open}${acc}${p.close}`, inner);
+function findBase(sf) {
+  let found;
+  sf.forEachDescendant((node, traversal) => {
+    if (Node.isJsxExpression(node)) {
+      const expr = node.getExpression();
+      if (expr && Node.isIdentifier(expr) && expr.getText() === "children") {
+        found = node;
+        traversal.stop();
+      }
+      return;
+    }
+    if (Node.isJsxSelfClosingElement(node)) {
+      if (node.getTagNameNode().getText() === "App") {
+        found = node;
+        traversal.stop();
+      }
+    }
+  });
+  return found;
+}
+function analyze(sf, names) {
+  const base = findBase(sf);
+  if (!base) return void 0;
+  let target = base;
+  const innerToOuter = [];
+  let parent = base.getParent();
+  while (parent && Node.isJsxElement(parent)) {
+    const tag = parent.getOpeningElement().getTagNameNode().getText();
+    if (!names.includes(tag)) break;
+    innerToOuter.push(tag);
+    target = parent;
+    parent = parent.getParent();
+  }
+  return { target, present: innerToOuter.reverse() };
+}
+function patchRootLayout(entryFile, providers, mount) {
+  const project = new Project({
+    manipulationSettings: {
+      indentationText: IndentationText.TwoSpaces,
+      quoteKind: QuoteKind.Double
+    }
+  });
+  const sf = project.addSourceFileAtPath(entryFile);
+  const names = providers.map((p) => p.name);
+  const importedNames = new Set(
+    sf.getImportDeclarations().flatMap((d) => d.getNamedImports().map((n) => n.getName()))
+  );
+  for (const p of providers) {
+    if (importedNames.has(p.name)) continue;
+    const imp = sf.getImportDeclaration(p.module) ?? sf.addImportDeclaration({ namedImports: [], moduleSpecifier: p.module });
+    imp.addNamedImport({ name: p.name });
+    importedNames.add(p.name);
+  }
+  if (mount && !sf.getImportDeclaration(mount.specifier))
+    sf.addImportDeclaration({
+      defaultImport: mount.component,
+      moduleSpecifier: mount.specifier
+    });
+  const located = analyze(sf, names);
+  if (!located)
+    throw new CliError(
+      "could not locate the root children expression in entry file",
+      3
+    );
+  const base = findBase(sf);
+  const missing = providers.filter((p) => !located.present.includes(p.name));
+  const hasMount = mount ? sf.getFullText().includes(`<${mount.component}`) : true;
+  let inner = located.target.getText();
+  if (mount && !hasMount && base) {
+    const baseText = base.getText();
+    inner = inner.replace(baseText, `<${mount.component} />${baseText}`);
+  }
+  if (missing.length > 0 || mount && !hasMount)
+    located.target.replaceWithText(wrap2(missing, inner));
+  return sf.getFullText();
+}
+async function assertEntryClean(entryFile, cwd, force) {
+  if (force) return;
+  try {
+    const { stdout } = await execFileAsync(
+      "git",
+      ["status", "--porcelain", "--", entryFile],
+      { cwd }
+    );
+    if (stdout.trim() !== "")
+      throw new CliError(
+        "entry file has uncommitted changes; commit/stash or re-run with --force",
+        3
+      );
+  } catch (err) {
+    if (err instanceof CliError) throw err;
+    consola2.warn(
+      `could not check git status for ${entryFile}; proceeding without the dirty-file guard`
+    );
+  }
+}
+
+// src/commands/add.ts
+var installSpecs = (r) => r.packages.map((p) => `${p}@${r.deps[p]}`);
+var allInstallSpecs = (r) => [
+  ...installSpecs(r),
+  ...runtimePeerSpecs(r.packages)
+];
+var installArgs = (pm, specs) => pm === "npm" ? ["install", "--save-exact", "--legacy-peer-deps", ...specs] : pm === "yarn" ? ["add", "--exact", ...specs] : pm === "bun" ? ["add", "--exact", ...specs] : ["add", "--save-exact", ...specs];
+var toursSpecifier = (recipe, cwd, entryFile, suffix) => {
+  const rel = relative(
+    dirname(entryFile),
+    join2(cwd, "tours", `${recipe.id}${suffix}`)
+  ).split(/[/\\]/).join("/");
+  return rel.startsWith(".") ? rel : `./${rel}`;
+};
+var mountSpec = (recipe, cwd, entryFile) => ({
+  component: `RecipeMount_${recipe.id.replace(/[^A-Za-z0-9]+/g, "_")}`,
+  specifier: toursSpecifier(recipe, cwd, entryFile, "")
+});
+var providersSpecifier = (recipe, cwd, entryFile) => toursSpecifier(recipe, cwd, entryFile, ".providers");
+var providersShim = (tier) => {
+  const lines = ['"use client";'];
+  if (tier === "pro")
+    lines.push('export { LicenseProvider } from "@tour-kit/license";');
+  lines.push('export { TourKitProvider } from "@tour-kit/react";');
+  return `${lines.join("\n")}
+`;
+};
+var assertPatchSupported = (framework) => {
+  if (framework !== "next-app" && framework !== "vite-react")
+    throw new CliError(
+      `provider patch for ${framework} is not supported in v0.1`,
+      2
+    );
+};
+async function ensureLicenseEnv(cwd, name) {
+  const line = `${name}=`;
+  for (const file of [".env.local", ".env.example"]) {
+    const abs = join2(cwd, file);
+    const existing = existsSync2(abs) ? await readFile(abs, "utf8") : "";
+    const present = existing.split(/\r?\n/).some((l) => l.trimStart().startsWith(line));
+    if (present) continue;
+    const sep = existing === "" || existing.endsWith("\n") ? "" : "\n";
+    await writeFile(abs, `${existing}${sep}${line}
+`);
+  }
+}
+async function runFormatter(project, cwd, files, json) {
+  if (!project.formatter) return;
+  const args = project.formatter === "biome" ? ["format", "--write", ...files] : ["--write", ...files];
+  try {
+    await execa(project.formatter, args, { cwd, preferLocal: true });
+  } catch {
+    if (!json)
+      consola3.warn(
+        `formatter "${project.formatter}" failed; files written unformatted`
+      );
+  }
+}
+async function runAdd(args) {
+  const json = Boolean(args.json);
+  const cwd = args.cwd ?? process.cwd();
+  const recipe = await fetchRecipe(args.recipe, args.base);
+  const project = await detectProject(cwd);
+  assertPatchSupported(project.framework);
+  const providers = providerStack(
+    recipe.tier,
+    project.licenseEnv.expression,
+    providersSpecifier(recipe, cwd, project.entryFile)
+  );
+  const shim = {
+    path: `tours/${recipe.id}.providers.ts`,
+    contents: providersShim(recipe.tier)
+  };
+  const files = [...expand(recipe), shim];
+  const patched = patchRootLayout(
+    project.entryFile,
+    providers,
+    mountSpec(recipe, cwd, project.entryFile)
+  );
+  const peers = runtimePeerSpecs(recipe.packages);
+  const specs = allInstallSpecs(recipe);
+  if (args["dry-run"]) {
+    const result2 = {
+      ok: true,
+      framework: project.framework,
+      packages: recipe.packages,
+      runtimePeers: peers,
+      filesWritten: files.map((f) => f.path),
+      providerPatched: patched !== await readFile(project.entryFile, "utf8")
+    };
+    if (json) {
+      emitResult(result2, true);
+    } else {
+      const current = await readFile(project.entryFile, "utf8");
+      consola3.box(
+        [
+          "Dry run \u2014 nothing written",
+          `install:  ${project.packageManager} ${installArgs(project.packageManager, specs).join(" ")}`,
+          `peers:    ${peers.join(", ") || "(none)"}`,
+          `files:    ${files.map((f) => f.path).join(", ")}`,
+          `entry:    ${project.entryFile}${patched === current ? " (already patched)" : " (would patch providers)"}`
+        ].join("\n")
+      );
+    }
+    return;
+  }
+  await assertEntryClean(project.entryFile, cwd, Boolean(args.force));
+  if (!args["no-install"]) {
+    try {
+      await execa(
+        project.packageManager,
+        installArgs(project.packageManager, specs),
+        { cwd }
+      );
+    } catch (err) {
+      throw new CliError(
+        `install failed: ${err instanceof Error ? err.message : String(err)}`,
+        1
+      );
+    }
+  }
+  const filesWritten = [];
+  for (const f of files) {
+    const abs = join2(cwd, f.path);
+    if (existsSync2(abs) && !args.overwrite) {
+      if (!json)
+        consola3.warn(`skipped existing ${f.path} (use --overwrite to replace)`);
+      continue;
+    }
+    await mkdir(dirname(abs), { recursive: true });
+    await writeFile(abs, f.contents);
+    filesWritten.push(f.path);
+  }
+  await writeFile(project.entryFile, patched);
+  await runFormatter(
+    project,
+    cwd,
+    [project.entryFile, ...filesWritten.map((p) => join2(cwd, p))],
+    json
+  );
+  if (recipe.tier === "pro")
+    await ensureLicenseEnv(cwd, project.licenseEnv.name);
+  const result = {
+    ok: true,
+    framework: project.framework,
+    packages: recipe.packages,
+    runtimePeers: peers,
+    filesWritten,
+    providerPatched: true
+  };
+  if (json) {
+    emitResult(result, true);
+    return;
+  }
+  consola3.success(`Detected ${project.framework} (${project.packageManager})`);
+  if (!args["no-install"]) {
+    consola3.success(`Installed ${recipe.packages.join(", ") || "(none)"}`);
+    if (peers.length > 0)
+      consola3.success(`Installed runtime peers ${peers.join(", ")}`);
+  }
+  consola3.success(`Scaffolded ${filesWritten.join(", ") || "(no new files)"}`);
+  consola3.success(`Patched providers into ${project.entryFile}`);
+}
+var add = defineCommand({
+  meta: {
+    name: "add",
+    description: "Install a recipe into this project"
+  },
+  args: {
+    recipe: {
+      type: "positional",
+      description: "Recipe id to add",
+      required: true
+    },
+    cwd: { type: "string", description: "Project root (defaults to .)" },
+    base: {
+      type: "string",
+      description: "Recipe API base URL (defaults to the Studio API)"
+    },
+    "dry-run": {
+      type: "boolean",
+      description: "Print the plan, change nothing"
+    },
+    yes: { type: "boolean", description: "Skip confirmation prompts" },
+    "no-install": {
+      type: "boolean",
+      description: "Scaffold without installing"
+    },
+    overwrite: {
+      type: "boolean",
+      description: "Overwrite an existing scaffold file"
+    },
+    force: {
+      type: "boolean",
+      description: "Patch even a git-dirty entry file"
+    },
+    json: { type: "boolean", description: "Emit one machine-readable result" }
+  },
+  run: ({ args }) => runOrExit(() => runAdd(args))
+});
+
+// src/commands/harden.ts
+import { defineCommand as defineCommand2 } from "citty";
+import { consola as consola4 } from "consola";
+var harden = defineCommand2({
+  meta: {
+    name: "harden",
+    description: "Inject data-tour-id attributes on referenced elements (coming in a later phase)"
+  },
+  args: {
+    recipe: {
+      type: "positional",
+      description: "Recipe id(s) to harden",
+      required: false
+    },
+    cwd: { type: "string", description: "Project root (defaults to .)" },
+    json: { type: "boolean", description: "Emit machine-readable JSON" }
+  },
+  run: () => {
+    consola4.info(
+      "`tourkit harden` is not implemented in v0.1 \u2014 coming in a later phase."
+    );
+  }
+});
+
+// src/commands/init.ts
+import { defineCommand as defineCommand3 } from "citty";
+import { consola as consola5 } from "consola";
+var init = defineCommand3({
+  meta: {
+    name: "init",
+    description: "Create a tourkit.config.json manifest (coming in a later phase)"
+  },
+  args: {
+    cwd: { type: "string", description: "Project root (defaults to .)" },
+    json: { type: "boolean", description: "Emit machine-readable JSON" }
+  },
+  run: () => {
+    consola5.info(
+      "`tourkit init` is not implemented in v0.1 \u2014 coming in a later phase."
+    );
+  }
+});
+
+// src/commands/pull.ts
+import { defineCommand as defineCommand4 } from "citty";
+import { consola as consola6 } from "consola";
+var pull = defineCommand4({
+  meta: {
+    name: "pull",
+    description: "Re-sync a recipe (coming in a later phase)"
+  },
+  args: {
+    recipe: {
+      type: "positional",
+      description: "Recipe id to pull",
+      required: true
+    },
+    cwd: { type: "string", description: "Project root (defaults to .)" },
+    json: { type: "boolean", description: "Emit machine-readable JSON" }
+  },
+  run: () => {
+    consola6.info(
+      "`tourkit pull` is not implemented in v0.1 \u2014 coming in a later phase."
+    );
+  }
+});
+
+// src/commands/verify.ts
+import { defineCommand as defineCommand5 } from "citty";
+import { consola as consola7 } from "consola";
+var verify = defineCommand5({
+  meta: {
+    name: "verify",
+    description: "Check tour selectors against a running app (coming in a later phase)"
+  },
+  args: {
+    recipe: {
+      type: "positional",
+      description: "Recipe id(s) to verify",
+      required: false
+    },
+    cwd: { type: "string", description: "Project root (defaults to .)" },
+    json: { type: "boolean", description: "Emit machine-readable JSON" }
+  },
+  run: () => {
+    consola7.info(
+      "`tourkit verify` is not implemented in v0.1 \u2014 coming in a later phase."
+    );
+  }
+});
+
+// src/index.ts
+runMain(
+  defineCommand6({
+    meta: {
+      name: "tourkit",
+      version: "0.1.0",
+      description: "User Tour Kit Studio CLI"
+    },
+    subCommands: { add, pull, verify, harden, init }
+  })
+);