refactor(snippets): adopt alias/title model and markdown UX

- rename snippet identity from name to alias and add required title fields

- migrate snippet API, forms, cards, and detail views to alias/title semantics

- render markdown descriptions with short card previews and split vendor chunks

server/src/code-executor/code-executor.service.ts

@@ -104,18 +104,18 @@ export class CodeExecutorService {
           return value;
         },
         /**
-         * Runs a named snippet by name. Snippets receive the same page/context/helpers
+         * Runs a snippet by alias. Snippets receive the same page/context/helpers
          * as regular exec code, plus any positional args you pass.
          *
          * Example: await helpers.runSnippet('clickLoginButton', '#submit')
          */
         runSnippet: async (
-          name: string,
+          alias: string,
           ...args: unknown[]
         ): Promise<unknown> => {
-          const snippetCode = snippetMap[name];
+          const snippetCode = snippetMap[alias];
           if (snippetCode == null) {
-            throw new Error(`Snippet "${name}" not found`);
+            throw new Error(`Snippet alias "${alias}" not found`);
           }
           const snippetFn = new Function(
             "page",

server/src/snippet/dto/create-snippet.dto.ts

@@ -5,7 +5,12 @@ export class CreateSnippetDto {
   @ApiProperty({ example: "clickLoginButton" })
   @IsString()
   @IsNotEmpty()
-  name: string;
+  alias: string;
+
+  @ApiProperty({ example: "Click Login Button" })
+  @IsString()
+  @IsNotEmpty()
+  title: string;
 
   @ApiPropertyOptional({
     example: "Clicks the login button and waits for navigation",

server/src/snippet/dto/snippet-export.dto.ts

@@ -18,10 +18,22 @@ export class SnippetExportDto {
   @IsUUID()
   id?: string;
 
-  @ApiProperty()
+  @ApiPropertyOptional()
+  @IsOptional()
   @IsString()
   @IsNotEmpty()
-  name: string;
+  alias?: string;
+
+  @ApiPropertyOptional()
+  @IsOptional()
+  @IsString()
+  @IsNotEmpty()
+  title?: string;
+
+  @ApiPropertyOptional({ deprecated: true })
+  @IsOptional()
+  @IsString()
+  name?: string;
 
   @ApiPropertyOptional()
   @IsOptional()

server/src/snippet/dto/update-snippet.dto.ts

@@ -6,7 +6,13 @@ export class UpdateSnippetDto {
   @IsOptional()
   @IsString()
   @IsNotEmpty()
-  name?: string;
+  alias?: string;
+
+  @ApiPropertyOptional({ example: "Click Login Button" })
+  @IsOptional()
+  @IsString()
+  @IsNotEmpty()
+  title?: string;
 
   @ApiPropertyOptional()
   @IsOptional()

server/src/snippet/snippet.controller.ts

@@ -25,7 +25,7 @@ export class SnippetController {
   @Post()
   @ApiOperation({ summary: "Create a new snippet" })
   @ApiResponse({ status: 201, description: "Snippet created" })
-  @ApiResponse({ status: 409, description: "Name already taken" })
+  @ApiResponse({ status: 409, description: "Alias already taken" })
   create(@Body() dto: CreateSnippetDto) {
     return this.snippetService.create(dto);
   }
@@ -65,7 +65,7 @@ export class SnippetController {
   @ApiOperation({ summary: "Update a snippet" })
   @ApiResponse({ status: 200, description: "Snippet updated" })
   @ApiResponse({ status: 404, description: "Snippet not found" })
-  @ApiResponse({ status: 409, description: "Name already taken" })
+  @ApiResponse({ status: 409, description: "Alias already taken" })
   update(
     @Param("id", ParseUUIDPipe) id: string,
     @Body() dto: UpdateSnippetDto,

server/src/snippet/snippet.entity.ts

@@ -11,9 +11,13 @@ export class SnippetEntity {
   @PrimaryGeneratedColumn("uuid")
   id: string;
 
-  /** Unique identifier used to call the snippet: helpers.runSnippet('mySnippet', ...) */
-  @Column({ unique: true })
-  name: string;
+  /** Unique identifier used to invoke the snippet: helpers.runSnippet('mySnippet', ...) */
+  @Column({ unique: true, nullable: true })
+  alias: string;
+
+  /** Human-readable title displayed in the UI. */
+  @Column({ default: "" })
+  title: string;
 
   @Column("text", { nullable: true })
   description: string | null;

server/src/snippet/snippet.service.ts

@@ -2,6 +2,7 @@ import {
   ConflictException,
   Injectable,
   NotFoundException,
+  OnModuleInit,
 } from "@nestjs/common";
 import { InjectRepository } from "@nestjs/typeorm";
 import { Repository } from "typeorm";
@@ -14,22 +15,47 @@ import {
   PaginatedResult,
 } from "../common/dto/pagination.dto";
 
-export type SnippetOrderBy = "id" | "name" | "createdAt" | "updatedAt";
+export type SnippetOrderBy = "id" | "alias" | "title" | "createdAt" | "updatedAt";
 
 @Injectable()
-export class SnippetService {
+export class SnippetService implements OnModuleInit {
   constructor(
     @InjectRepository(SnippetEntity)
     private readonly repo: Repository<SnippetEntity>,
   ) {}
 
+  async onModuleInit(): Promise<void> {
+    // Best-effort backfill for existing DBs that still have legacy `name` values.
+    try {
+      await this.repo.query(
+        "UPDATE snippets SET alias = name WHERE (alias IS NULL OR alias = '') AND name IS NOT NULL",
+      );
+    } catch {
+      // Ignore when legacy `name` column does not exist.
+    }
+    try {
+      await this.repo.query(
+        "UPDATE snippets SET title = COALESCE(alias, name, '') WHERE title IS NULL OR title = ''",
+      );
+    } catch {
+      await this.repo.query(
+        "UPDATE snippets SET title = COALESCE(alias, '') WHERE title IS NULL OR title = ''",
+      );
+    }
+  }
+
   async create(dto: CreateSnippetDto): Promise<SnippetEntity> {
-    const existing = await this.repo.findOneBy({ name: dto.name });
+    const existing = await this.repo.findOneBy({ alias: dto.alias });
     if (existing) {
-      throw new ConflictException(`Snippet "${dto.name}" already exists`);
+      throw new ConflictException(`Snippet alias "${dto.alias}" already exists`);
     }
     return this.repo.save(
-      this.repo.create({ ...dto, description: dto.description ?? null }),
+      this.repo.create({
+        alias: dto.alias,
+        title: dto.title,
+        description: dto.description ?? null,
+        code: dto.code,
+      }),
     );
   }
 
@@ -56,10 +82,10 @@ export class SnippetService {
 
   async update(id: string, dto: UpdateSnippetDto): Promise<SnippetEntity> {
     const snippet = await this.findOne(id);
-    if (dto.name && dto.name !== snippet.name) {
-      const conflict = await this.repo.findOneBy({ name: dto.name });
+    if (dto.alias && dto.alias !== snippet.alias) {
+      const conflict = await this.repo.findOneBy({ alias: dto.alias });
       if (conflict)
-        throw new ConflictException(`Snippet "${dto.name}" already exists`);
+        throw new ConflictException(`Snippet alias "${dto.alias}" already exists`);
     }
     Object.assign(snippet, dto);
     return this.repo.save(snippet);
@@ -70,28 +96,36 @@ export class SnippetService {
     await this.repo.delete(id);
   }
 
-  /** Returns a name→code map for all snippets (used by the executor). */
+  /** Returns an alias→code map for all snippets (used by the executor). */
   async buildSnippetMap(): Promise<Record<string, string>> {
     const { data } = await this.findAll({ limit: 1000 });
-    return Object.fromEntries(data.map((s) => [s.name, s.code]));
+    return Object.fromEntries(data.map((s) => [s.alias, s.code]));
   }
 
   exportSnippet(snippet: SnippetEntity): SnippetExportDto {
     return {
       kind: "snippet",
       id: snippet.id,
-      name: snippet.name,
+      alias: snippet.alias,
+      title: snippet.title,
       description: snippet.description,
       code: snippet.code,
     };
   }
 
   async importSnippet(dto: SnippetExportDto): Promise<SnippetEntity> {
+    const alias = dto.alias ?? dto.name;
+    if (!alias) {
+      throw new ConflictException("Snippet alias is required");
+    }
+    const title = dto.title ?? alias;
+
     if (dto.id) {
       const existing = await this.repo.findOneBy({ id: dto.id });
       if (existing) {
         Object.assign(existing, {
-          name: dto.name,
+          alias,
+          title,
           description: dto.description ?? null,
           code: dto.code,
         });
@@ -100,7 +134,8 @@ export class SnippetService {
       return this.repo.save(
         this.repo.create({
           id: dto.id,
-          name: dto.name,
+          alias,
+          title,
           description: dto.description ?? null,
           code: dto.code,
         }),
@@ -108,7 +143,8 @@ export class SnippetService {
     }
     return this.repo.save(
       this.repo.create({
-        name: dto.name,
+        alias,
+        title,
         description: dto.description ?? null,
         code: dto.code,
       }),