@contractspec/example.learning-journey-studio-onboarding 1.56.1 → 1.58.0

package/dist/browser/index.js

@@ -0,0 +1,393 @@
+// src/docs/studio-onboarding.docblock.ts
+import { registerDocBlocks } from "@contractspec/lib.contracts";
+var studioOnboardingDocBlocks = [
+  {
+    id: "docs.learning-journey.studio-onboarding",
+    title: "Learning Journey — Studio Getting Started",
+    summary: "Track that guides a new Studio user through template spawn, spec edit, regeneration, playground, and evolution.",
+    kind: "reference",
+    visibility: "public",
+    route: "/docs/learning-journey/studio-onboarding",
+    tags: ["learning", "onboarding", "studio"],
+    body: `## Track
+- **Key**: \`studio_getting_started\`
+- **Persona**: new Studio developer, first 30 minutes
+- **Goal**: instantiate template → edit spec → regenerate → play → run evolution
+
+## Steps & Events
+1) \`choose_template\` → event \`studio.template.instantiated\`
+2) \`edit_spec\` → event \`spec.changed\` (scope: sandbox)
+3) \`regenerate_app\` → event \`regeneration.completed\`
+4) \`play_in_playground\` → event \`playground.session.started\`
+5) \`try_evolution_mode\` → event \`studio.evolution.applied\`
+
+XP: 20/20/20/20/30 with bonus 25 XP if completed within 48h (streak rule). Badge: \`studio_first_30m\`.
+
+## Wiring
+- Tracks export from \`@contractspec/example.learning-journey-studio-onboarding/track\`.
+- Use onboarding API:
+  - \`learning.onboarding.listTracks\` to surface catalog
+  - \`learning.onboarding.getProgress\` to render progress
+  - \`learning.onboarding.recordEvent\` to advance from bus events
+- Events should be emitted by Studio surfaces (template creation, spec save, regeneration, playground session start, evolution apply).`
+  }
+];
+registerDocBlocks(studioOnboardingDocBlocks);
+// src/example.ts
+import { defineExample } from "@contractspec/lib.contracts";
+var example = defineExample({
+  meta: {
+    key: "learning-journey-studio-onboarding",
+    version: "1.0.0",
+    title: "Learning Journey — Studio Getting Started",
+    description: "Onboarding track guiding a new Studio user through template spawn, spec edit, regeneration, playground, and evolution.",
+    kind: "template",
+    visibility: "public",
+    stability: "experimental",
+    owners: ["@platform.core"],
+    tags: ["learning", "onboarding", "studio"]
+  },
+  docs: {
+    rootDocId: "docs.learning-journey.studio-onboarding"
+  },
+  entrypoints: {
+    packageName: "@contractspec/example.learning-journey-studio-onboarding",
+    docs: "./docs"
+  },
+  surfaces: {
+    templates: true,
+    sandbox: { enabled: true, modes: ["playground", "markdown"] },
+    studio: { enabled: true, installable: true },
+    mcp: { enabled: true }
+  }
+});
+var example_default = example;
+
+// src/track.ts
+var studioGettingStartedTrack = {
+  id: "studio_getting_started",
+  productId: "contractspec-studio",
+  name: "Studio Getting Started",
+  description: "First 30 minutes in Studio: create a project, edit the spec, deploy/regenerate, and try key modules.",
+  targetUserSegment: "new_studio_user",
+  targetRole: "developer",
+  totalXp: 110,
+  streakRule: { hoursWindow: 48, bonusXp: 25 },
+  completionRewards: { xpBonus: 25, badgeKey: "studio_first_30m" },
+  steps: [
+    {
+      id: "choose_template",
+      title: "Choose a template",
+      description: "Create your first Studio project (starter template).",
+      order: 1,
+      completion: {
+        eventName: "studio.template.instantiated",
+        sourceModule: "@contractspec/bundle.studio"
+      },
+      xpReward: 20,
+      metadata: { surface: "projects" }
+    },
+    {
+      id: "edit_spec",
+      title: "Edit the spec",
+      description: "Change the spec (not generated code) and save.",
+      instructions: "Open spec editor, tweak a contract or presentation, save.",
+      order: 2,
+      completion: {
+        eventName: "spec.changed",
+        sourceModule: "@contractspec/bundle.studio"
+      },
+      xpReward: 20,
+      metadata: { surface: "spec-editor" }
+    },
+    {
+      id: "regenerate_app",
+      title: "Regenerate the app",
+      description: "Regenerate artifacts from the updated spec.",
+      order: 3,
+      completion: {
+        eventName: "regeneration.completed",
+        sourceModule: "@contractspec/lib.contracts/regenerator"
+      },
+      xpReward: 20,
+      metadata: { surface: "regenerator" }
+    },
+    {
+      id: "open_canvas",
+      title: "Open the canvas",
+      description: "Visit the canvas module for your project.",
+      order: 4,
+      completion: {
+        eventName: "module.navigated",
+        sourceModule: "@contractspec/bundle.studio",
+        payloadFilter: { moduleId: "canvas" }
+      },
+      xpReward: 20,
+      metadata: { surface: "canvas" }
+    },
+    {
+      id: "try_evolution_mode",
+      title: "Try evolution mode",
+      description: "Request a change via Evolution, then regenerate.",
+      order: 5,
+      completion: {
+        eventName: "studio.evolution.applied",
+        sourceModule: "@contractspec/lib.evolution"
+      },
+      xpReward: 30,
+      metadata: { surface: "evolution" }
+    }
+  ],
+  metadata: {
+    persona: "first_run",
+    surfacedIn: ["studio/home", "studio/sidebar/learning"]
+  }
+};
+var studioLearningTracks = [
+  studioGettingStartedTrack
+];
+
+// src/handlers/demo.handlers.ts
+var studioOnboardingEvents = [
+  "studio.template.instantiated",
+  "spec.changed",
+  "regeneration.completed",
+  "playground.session.started",
+  "studio.evolution.applied"
+];
+var emitStudioOnboardingEvent = (eventName, { learnerId, occurredAt = new Date }, record) => {
+  const event = {
+    learnerId,
+    name: eventName,
+    occurredAt,
+    trackId: studioGettingStartedTrack.id
+  };
+  return record ? record(event) : event;
+};
+var emitAllStudioOnboardingEvents = (params, record) => studioOnboardingEvents.map((name) => emitStudioOnboardingEvent(name, params, record));
+
+// src/operations/index.ts
+import { ScalarTypeEnum, defineSchemaModel } from "@contractspec/lib.schema";
+import { defineCommand, defineQuery } from "@contractspec/lib.contracts";
+var OWNERS = ["examples.learning-journey.studio-onboarding"];
+var StepModel = defineSchemaModel({
+  name: "StudioOnboardingStep",
+  description: "Step metadata for Studio onboarding journey",
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    title: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    description: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    completionEvent: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false
+    },
+    sourceModule: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    xpReward: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true },
+    order: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true }
+  }
+});
+var StudioOnboardingTrackModel = defineSchemaModel({
+  name: "StudioOnboardingTrack",
+  description: "Studio onboarding track definition",
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    name: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    description: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    totalXp: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true },
+    completionXpBonus: {
+      type: ScalarTypeEnum.Int_unsecure(),
+      isOptional: true
+    },
+    completionBadgeKey: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: true
+    },
+    streakHoursWindow: {
+      type: ScalarTypeEnum.Int_unsecure(),
+      isOptional: true
+    },
+    streakBonusXp: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true },
+    steps: { type: StepModel, isArray: true, isOptional: false }
+  }
+});
+var TrackResponseModel = defineSchemaModel({
+  name: "StudioOnboardingTrackResponse",
+  description: "Response wrapper for studio onboarding track",
+  fields: {
+    track: { type: StudioOnboardingTrackModel, isOptional: false }
+  }
+});
+var RecordDemoEventInput = defineSchemaModel({
+  name: "StudioOnboardingRecordEventInput",
+  description: "Emit a demo event to advance Studio onboarding steps",
+  fields: {
+    learnerId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    eventName: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    payload: { type: ScalarTypeEnum.JSON(), isOptional: true },
+    occurredAt: { type: ScalarTypeEnum.DateTime(), isOptional: true }
+  }
+});
+var SuccessModel = defineSchemaModel({
+  name: "StudioOnboardingSuccess",
+  description: "Generic success response",
+  fields: {
+    success: { type: ScalarTypeEnum.Boolean(), isOptional: false }
+  }
+});
+var GetStudioOnboardingTrack = defineQuery({
+  meta: {
+    key: "learningJourney.studioOnboarding.getTrack",
+    version: "1.0.0",
+    stability: "experimental",
+    owners: [...OWNERS],
+    tags: ["learning", "onboarding", "studio"],
+    description: "Fetch the Studio onboarding track definition.",
+    goal: "Expose track metadata to UIs and templates.",
+    context: "Called by Studio/Playground to render journey steps."
+  },
+  io: {
+    input: defineSchemaModel({
+      name: "StudioOnboardingTrackInput",
+      description: "Track input",
+      fields: {}
+    }),
+    output: TrackResponseModel
+  },
+  policy: { auth: "user" }
+});
+var RecordStudioOnboardingEvent = defineCommand({
+  meta: {
+    key: "learningJourney.studioOnboarding.recordEvent",
+    version: "1.0.0",
+    stability: "experimental",
+    owners: [...OWNERS],
+    tags: ["learning", "onboarding", "studio"],
+    description: "Record an event to advance Studio onboarding progress.",
+    goal: "Advance steps via domain events in demo/sandbox contexts.",
+    context: "Called by handlers or demo scripts to emit step completion events."
+  },
+  io: {
+    input: RecordDemoEventInput,
+    output: SuccessModel
+  },
+  policy: { auth: "user" }
+});
+var studioOnboardingContracts = {
+  GetStudioOnboardingTrack,
+  RecordStudioOnboardingEvent,
+  track: studioGettingStartedTrack
+};
+
+// src/presentations/index.ts
+import {
+  definePresentation,
+  StabilityEnum
+} from "@contractspec/lib.contracts";
+var baseMeta = {
+  domain: "learning-journey",
+  title: "Studio Onboarding",
+  owners: ["@examples.learning-journey.studio-onboarding"],
+  tags: ["learning", "onboarding", "studio"],
+  stability: StabilityEnum.Experimental
+};
+var StudioOnboardingTrackPresentation = definePresentation({
+  meta: {
+    key: "learning.journey.studio.track",
+    version: "1.0.0",
+    description: "Studio onboarding track detail",
+    goal: "Visualize the onboarding track for the user.",
+    context: "Displayed in the Studio dashboard.",
+    ...baseMeta
+  },
+  source: {
+    type: "component",
+    framework: "react",
+    componentKey: "LearningTrackDetail",
+    props: StudioOnboardingTrackModel
+  },
+  targets: ["react", "markdown", "application/json"]
+});
+var StudioOnboardingWidgetPresentation = definePresentation({
+  meta: {
+    key: "learning.journey.studio.widget",
+    version: "1.0.0",
+    description: "Compact widget for Studio onboarding progress",
+    goal: "Show quick progress summary.",
+    context: "Displayed in the Studio sidebar or header.",
+    ...baseMeta
+  },
+  source: {
+    type: "component",
+    framework: "react",
+    componentKey: "LearningTrackProgressWidget"
+  },
+  targets: ["react"]
+});
+var studioOnboardingPresentations = [
+  StudioOnboardingTrackPresentation,
+  StudioOnboardingWidgetPresentation
+];
+
+// src/learning-journey-studio-onboarding.feature.ts
+import { defineFeature } from "@contractspec/lib.contracts";
+var LearningJourneyStudioOnboardingFeature = defineFeature({
+  meta: {
+    key: "learning-journey-studio-onboarding",
+    title: "Learning Journey: Studio Onboarding",
+    description: "Studio onboarding journey for getting started with ContractSpec Studio",
+    domain: "learning-journey",
+    owners: ["@examples.learning-journey.studio-onboarding"],
+    tags: ["learning", "onboarding", "studio", "journey"],
+    stability: "experimental",
+    version: "1.0.0"
+  },
+  operations: [
+    { key: "learningJourney.studioOnboarding.recordEvent", version: "1.0.0" },
+    { key: "learningJourney.studioOnboarding.getTrack", version: "1.0.0" }
+  ],
+  events: [],
+  presentations: [
+    { key: "learning.journey.studio.track", version: "1.0.0" },
+    { key: "learning.journey.studio.widget", version: "1.0.0" }
+  ],
+  opToPresentation: [
+    {
+      op: {
+        key: "learningJourney.studioOnboarding.getTrack",
+        version: "1.0.0"
+      },
+      pres: { key: "learning.journey.studio.track", version: "1.0.0" }
+    }
+  ],
+  presentationsTargets: [
+    {
+      key: "learning.journey.studio.track",
+      version: "1.0.0",
+      targets: ["react", "markdown", "application/json"]
+    },
+    {
+      key: "learning.journey.studio.widget",
+      version: "1.0.0",
+      targets: ["react"]
+    }
+  ],
+  capabilities: {
+    requires: [{ key: "identity", version: "1.0.0" }]
+  }
+});
+export {
+  studioOnboardingPresentations,
+  studioOnboardingEvents,
+  studioOnboardingContracts,
+  studioLearningTracks,
+  studioGettingStartedTrack,
+  example_default as example,
+  emitStudioOnboardingEvent,
+  emitAllStudioOnboardingEvents,
+  StudioOnboardingWidgetPresentation,
+  StudioOnboardingTrackPresentation,
+  StudioOnboardingTrackModel,
+  RecordStudioOnboardingEvent,
+  LearningJourneyStudioOnboardingFeature,
+  GetStudioOnboardingTrack
+};

package/dist/browser/learning-journey-studio-onboarding.feature.js

@@ -0,0 +1,50 @@
+// src/learning-journey-studio-onboarding.feature.ts
+import { defineFeature } from "@contractspec/lib.contracts";
+var LearningJourneyStudioOnboardingFeature = defineFeature({
+  meta: {
+    key: "learning-journey-studio-onboarding",
+    title: "Learning Journey: Studio Onboarding",
+    description: "Studio onboarding journey for getting started with ContractSpec Studio",
+    domain: "learning-journey",
+    owners: ["@examples.learning-journey.studio-onboarding"],
+    tags: ["learning", "onboarding", "studio", "journey"],
+    stability: "experimental",
+    version: "1.0.0"
+  },
+  operations: [
+    { key: "learningJourney.studioOnboarding.recordEvent", version: "1.0.0" },
+    { key: "learningJourney.studioOnboarding.getTrack", version: "1.0.0" }
+  ],
+  events: [],
+  presentations: [
+    { key: "learning.journey.studio.track", version: "1.0.0" },
+    { key: "learning.journey.studio.widget", version: "1.0.0" }
+  ],
+  opToPresentation: [
+    {
+      op: {
+        key: "learningJourney.studioOnboarding.getTrack",
+        version: "1.0.0"
+      },
+      pres: { key: "learning.journey.studio.track", version: "1.0.0" }
+    }
+  ],
+  presentationsTargets: [
+    {
+      key: "learning.journey.studio.track",
+      version: "1.0.0",
+      targets: ["react", "markdown", "application/json"]
+    },
+    {
+      key: "learning.journey.studio.widget",
+      version: "1.0.0",
+      targets: ["react"]
+    }
+  ],
+  capabilities: {
+    requires: [{ key: "identity", version: "1.0.0" }]
+  }
+});
+export {
+  LearningJourneyStudioOnboardingFeature
+};

package/dist/browser/operations/index.js

@@ -0,0 +1,201 @@
+// src/track.ts
+var studioGettingStartedTrack = {
+  id: "studio_getting_started",
+  productId: "contractspec-studio",
+  name: "Studio Getting Started",
+  description: "First 30 minutes in Studio: create a project, edit the spec, deploy/regenerate, and try key modules.",
+  targetUserSegment: "new_studio_user",
+  targetRole: "developer",
+  totalXp: 110,
+  streakRule: { hoursWindow: 48, bonusXp: 25 },
+  completionRewards: { xpBonus: 25, badgeKey: "studio_first_30m" },
+  steps: [
+    {
+      id: "choose_template",
+      title: "Choose a template",
+      description: "Create your first Studio project (starter template).",
+      order: 1,
+      completion: {
+        eventName: "studio.template.instantiated",
+        sourceModule: "@contractspec/bundle.studio"
+      },
+      xpReward: 20,
+      metadata: { surface: "projects" }
+    },
+    {
+      id: "edit_spec",
+      title: "Edit the spec",
+      description: "Change the spec (not generated code) and save.",
+      instructions: "Open spec editor, tweak a contract or presentation, save.",
+      order: 2,
+      completion: {
+        eventName: "spec.changed",
+        sourceModule: "@contractspec/bundle.studio"
+      },
+      xpReward: 20,
+      metadata: { surface: "spec-editor" }
+    },
+    {
+      id: "regenerate_app",
+      title: "Regenerate the app",
+      description: "Regenerate artifacts from the updated spec.",
+      order: 3,
+      completion: {
+        eventName: "regeneration.completed",
+        sourceModule: "@contractspec/lib.contracts/regenerator"
+      },
+      xpReward: 20,
+      metadata: { surface: "regenerator" }
+    },
+    {
+      id: "open_canvas",
+      title: "Open the canvas",
+      description: "Visit the canvas module for your project.",
+      order: 4,
+      completion: {
+        eventName: "module.navigated",
+        sourceModule: "@contractspec/bundle.studio",
+        payloadFilter: { moduleId: "canvas" }
+      },
+      xpReward: 20,
+      metadata: { surface: "canvas" }
+    },
+    {
+      id: "try_evolution_mode",
+      title: "Try evolution mode",
+      description: "Request a change via Evolution, then regenerate.",
+      order: 5,
+      completion: {
+        eventName: "studio.evolution.applied",
+        sourceModule: "@contractspec/lib.evolution"
+      },
+      xpReward: 30,
+      metadata: { surface: "evolution" }
+    }
+  ],
+  metadata: {
+    persona: "first_run",
+    surfacedIn: ["studio/home", "studio/sidebar/learning"]
+  }
+};
+var studioLearningTracks = [
+  studioGettingStartedTrack
+];
+
+// src/operations/index.ts
+import { ScalarTypeEnum, defineSchemaModel } from "@contractspec/lib.schema";
+import { defineCommand, defineQuery } from "@contractspec/lib.contracts";
+var OWNERS = ["examples.learning-journey.studio-onboarding"];
+var StepModel = defineSchemaModel({
+  name: "StudioOnboardingStep",
+  description: "Step metadata for Studio onboarding journey",
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    title: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    description: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    completionEvent: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: false
+    },
+    sourceModule: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    xpReward: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true },
+    order: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true }
+  }
+});
+var StudioOnboardingTrackModel = defineSchemaModel({
+  name: "StudioOnboardingTrack",
+  description: "Studio onboarding track definition",
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    name: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    description: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    totalXp: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true },
+    completionXpBonus: {
+      type: ScalarTypeEnum.Int_unsecure(),
+      isOptional: true
+    },
+    completionBadgeKey: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isOptional: true
+    },
+    streakHoursWindow: {
+      type: ScalarTypeEnum.Int_unsecure(),
+      isOptional: true
+    },
+    streakBonusXp: { type: ScalarTypeEnum.Int_unsecure(), isOptional: true },
+    steps: { type: StepModel, isArray: true, isOptional: false }
+  }
+});
+var TrackResponseModel = defineSchemaModel({
+  name: "StudioOnboardingTrackResponse",
+  description: "Response wrapper for studio onboarding track",
+  fields: {
+    track: { type: StudioOnboardingTrackModel, isOptional: false }
+  }
+});
+var RecordDemoEventInput = defineSchemaModel({
+  name: "StudioOnboardingRecordEventInput",
+  description: "Emit a demo event to advance Studio onboarding steps",
+  fields: {
+    learnerId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    eventName: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    payload: { type: ScalarTypeEnum.JSON(), isOptional: true },
+    occurredAt: { type: ScalarTypeEnum.DateTime(), isOptional: true }
+  }
+});
+var SuccessModel = defineSchemaModel({
+  name: "StudioOnboardingSuccess",
+  description: "Generic success response",
+  fields: {
+    success: { type: ScalarTypeEnum.Boolean(), isOptional: false }
+  }
+});
+var GetStudioOnboardingTrack = defineQuery({
+  meta: {
+    key: "learningJourney.studioOnboarding.getTrack",
+    version: "1.0.0",
+    stability: "experimental",
+    owners: [...OWNERS],
+    tags: ["learning", "onboarding", "studio"],
+    description: "Fetch the Studio onboarding track definition.",
+    goal: "Expose track metadata to UIs and templates.",
+    context: "Called by Studio/Playground to render journey steps."
+  },
+  io: {
+    input: defineSchemaModel({
+      name: "StudioOnboardingTrackInput",
+      description: "Track input",
+      fields: {}
+    }),
+    output: TrackResponseModel
+  },
+  policy: { auth: "user" }
+});
+var RecordStudioOnboardingEvent = defineCommand({
+  meta: {
+    key: "learningJourney.studioOnboarding.recordEvent",
+    version: "1.0.0",
+    stability: "experimental",
+    owners: [...OWNERS],
+    tags: ["learning", "onboarding", "studio"],
+    description: "Record an event to advance Studio onboarding progress.",
+    goal: "Advance steps via domain events in demo/sandbox contexts.",
+    context: "Called by handlers or demo scripts to emit step completion events."
+  },
+  io: {
+    input: RecordDemoEventInput,
+    output: SuccessModel
+  },
+  policy: { auth: "user" }
+});
+var studioOnboardingContracts = {
+  GetStudioOnboardingTrack,
+  RecordStudioOnboardingEvent,
+  track: studioGettingStartedTrack
+};
+export {
+  studioOnboardingContracts,
+  StudioOnboardingTrackModel,
+  RecordStudioOnboardingEvent,
+  GetStudioOnboardingTrack
+};