@cyber-dash-tech/revela 0.4.0 → 0.4.1

package/lib/commands/designs-new.ts

@@ -0,0 +1,167 @@
+export interface DesignsNewArgs {
+  name: string
+  base: string
+}
+
+export type DesignsNewParseResult =
+  | { ok: true; name: string; base: string }
+  | { ok: false; error: string }
+
+export type DesignsEditParseResult =
+  | { ok: true; name: string }
+  | { ok: false; error: string }
+
+const USAGE =
+  "**Usage:** `/revela designs-new <kebab-case-name> [--base starter]`\n" +
+  "Example: `/revela designs-new neon-finance --base starter`"
+
+const EDIT_USAGE =
+  "**Usage:** `/revela designs-edit <kebab-case-name>`\n" +
+  "Example: `/revela designs-edit neon-finance`"
+
+function isValidDesignName(name: string): boolean {
+  return /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(name)
+}
+
+export function parseDesignsNewArgs(input: string): DesignsNewParseResult {
+  const tokens = input.trim().split(/\s+/).filter(Boolean)
+  if (tokens.length === 0) return { ok: false, error: USAGE }
+
+  const name = tokens[0]
+  if (!isValidDesignName(name)) {
+    return {
+      ok: false,
+      error: `${USAGE}\n\nDesign name must be kebab-case using lowercase letters, numbers, and hyphens.`,
+    }
+  }
+
+  let base = "starter"
+  for (let i = 1; i < tokens.length; i++) {
+    const token = tokens[i]
+    if (token === "--base") {
+      const value = tokens[i + 1]
+      if (!value) return { ok: false, error: `${USAGE}\n\nMissing value for --base.` }
+      if (!isValidDesignName(value)) {
+        return { ok: false, error: `${USAGE}\n\nBase design must be a valid kebab-case design name.` }
+      }
+      base = value
+      i++
+      continue
+    }
+    return { ok: false, error: `${USAGE}\n\nUnknown option: \`${token}\`` }
+  }
+
+  return { ok: true, name, base }
+}
+
+export function parseDesignsEditArgs(input: string): DesignsEditParseResult {
+  const tokens = input.trim().split(/\s+/).filter(Boolean)
+  if (tokens.length !== 1) return { ok: false, error: EDIT_USAGE }
+
+  const name = tokens[0]
+  if (!isValidDesignName(name)) {
+    return {
+      ok: false,
+      error: `${EDIT_USAGE}\n\nDesign name must be kebab-case using lowercase letters, numbers, and hyphens.`,
+    }
+  }
+
+  return { ok: true, name }
+}
+
+const VISUAL_QUALITY_RULES = `Visual extraction and CSS quality rules:
+- Before writing CSS, extract a visual schema from the user's references. Include reference type, composition, scale, anchoring, typography relationship, decorative language, must-preserve, and must-avoid.
+- Preserve composition, not just colors and shapes. If the reference is a bottom strip, compact badge, side rail, or sparse header mark, keep that scale and anchoring; do not enlarge it into a full-slide mascot or background unless requested.
+- Do not rewrite the entire base layout system from scratch. Preserve base layout/container CSS where possible; mainly change tokens, typography, component skins, and small decorative components.
+- Keep CSS scoped and boring. Prefer CSS variables and reusable classes over many one-off absolute-positioned selectors.
+- If a reference is flat vector, doodle, mascot, blob, line-art, or geometric illustration, prefer a self-contained SVG component with a fixed viewBox. CSS should place the SVG; the SVG should draw the motif.
+- If a reference is photography, UI screenshot, webpage, or product surface, do not convert it to SVG. Extract palette, type scale, spacing, layout rhythm, borders, and image treatment instead.
+- For SVG motifs: set a viewBox, keep all eyes/mouths/decorations inside that coordinate system, and document intended placement/scale in the component notes.
+- Before saving, review the preview for text overlap, scale drift, lost anchoring, overflow, and whether the preview preserves the reference composition.`
+
+export function buildDesignsNewPrompt({ name, base }: DesignsNewArgs): string {
+  return `You are creating a new Revela visual design package.
+
+Target design:
+- name: ${name}
+- base design: ${base}
+
+Use the base design only as a structural scaffold. Preserve its structure, not its visual identity.
+
+You must preserve from the base design:
+- marker structure: @design, @layout, and @component blocks
+- layout taxonomy and component coverage
+- HTML skeleton and SlidePresentation JavaScript architecture
+- 1920x1080 fixed canvas behavior
+- slide-qa usage on every slide
+- QA-friendly class vocabulary discipline
+
+You must replace unless the user explicitly requests otherwise:
+- palette
+- typography
+- imagery direction
+- decorative language
+- tone
+- composition rules
+- preview content
+
+${VISUAL_QUALITY_RULES}
+
+Workflow:
+1. Do not generate or save files immediately.
+2. Interview the user first. Ask for visual references such as screenshots/images, webpage URLs, text descriptions, brands, or decks they like.
+3. Extract a visual schema from the references before proposing CSS or components.
+4. Collect a concise design brief covering intent, tone, density, content mode, industry fit, references, visual schema, must-have, and must-avoid.
+5. Summarize the brief and visual schema, then ask the user to confirm them.
+6. After confirmation, inspect the base design using the \`revela-designs\` tool.
+7. Generate a complete \`DESIGN.md\` and matching \`preview.html\`.
+8. Self-review the preview against the visual schema before saving.
+9. Save the package with \`revela-designs-author\` using action \`create\`.
+10. Validate it with \`revela-designs-author\` using action \`validate\`.
+11. Report the saved path and activation command: \`/revela designs ${name}\`.
+
+Hard requirements:
+- \`DESIGN.md\` must include frontmatter with name, description, author, and version.
+- \`DESIGN.md\` must include valid \`@design\`, \`@layout\`, and \`@component\` markers.
+- \`DESIGN.md\` must include at least \`@design:foundation\`, \`@design:rules\`, one layout, and one component.
+- \`preview.html\` must be self-contained and directly openable in a browser.
+- Every preview slide must include \`slide-qa="true"\` or \`slide-qa="false"\`.
+- Do not save anything until the user confirms the brief.
+
+Start now by interviewing the user. Keep the first question concise.`
+}
+
+export function buildDesignsEditPrompt({ name }: { name: string }): string {
+  return `You are editing an existing Revela visual design package.
+
+Target design:
+- name: ${name}
+
+Goal:
+- Refine the existing design without losing its useful layout/component coverage.
+- Preserve the design's established structure unless the user explicitly asks to change it.
+- Save the edited design only after the user confirms the edit brief.
+
+${VISUAL_QUALITY_RULES}
+
+Workflow:
+1. Do not save files immediately.
+2. Ask the user what they want to change. Accept text descriptions, screenshots/images, webpage URLs, or specific complaints about the current preview.
+3. Inspect the existing design using \`revela-designs\` with action \`read\` and name \`${name}\`. Fetch relevant layouts/components as needed.
+4. Summarize an edit brief covering current issue, desired direction, visual schema, must-preserve, and must-avoid.
+5. Ask the user to confirm the edit brief.
+6. After confirmation, generate the updated complete \`DESIGN.md\` and updated complete \`preview.html\`.
+7. Self-review the preview for text overlap, scale drift, lost anchoring, overflow, and whether the requested change is visible.
+8. Save with \`revela-designs-author\` using action \`create\`, name \`${name}\`, and overwrite=true.
+9. Validate with \`revela-designs-author\` using action \`validate\`.
+10. Report the saved path and activation command: \`/revela designs ${name}\`.
+
+Hard requirements:
+- Preserve valid frontmatter and marker structure.
+- Preserve at least \`@design:foundation\`, \`@design:rules\`, one layout, and one component.
+- \`preview.html\` must be self-contained and directly openable in a browser.
+- Every preview slide must include \`slide-qa="true"\` or \`slide-qa="false"\`.
+- Do not save anything until the user confirms the edit brief.
+
+Start now by asking what the user wants to change in \`${name}\`.`
+}

package/lib/commands/designs-preview.ts

@@ -0,0 +1,36 @@
+import { resolveDesignPreview } from "../design/designs"
+
+function openFile(filePath: string): void {
+  if (process.platform === "darwin") {
+    const proc = Bun.spawnSync(["open", filePath])
+    if (proc.exitCode !== 0) throw new Error(proc.stderr.toString() || "Failed to open preview")
+    return
+  }
+
+  if (process.platform === "win32") {
+    const proc = Bun.spawnSync(["cmd", "/c", "start", "", filePath])
+    if (proc.exitCode !== 0) throw new Error(proc.stderr.toString() || "Failed to open preview")
+    return
+  }
+
+  const proc = Bun.spawnSync(["xdg-open", filePath])
+  if (proc.exitCode !== 0) throw new Error(proc.stderr.toString() || "Failed to open preview")
+}
+
+export async function handleDesignsPreview(
+  name: string,
+  send: (text: string) => Promise<void>,
+): Promise<void> {
+  try {
+    const preview = resolveDesignPreview(name || undefined)
+    if (!preview.hasPreview) {
+      await send(`Design \`${preview.name}\` has no \`preview.html\`.`)
+      return
+    }
+
+    openFile(preview.previewPath)
+    await send(`Opened preview for design \`${preview.name}\`: \`${preview.previewPath}\``)
+  } catch (e: any) {
+    await send(`**Preview failed:** ${e.message || String(e)}`)
+  }
+}

package/lib/commands/help.ts

@@ -28,6 +28,9 @@ export async function handleHelp(
     `\`/revela disable\`             — disable slide generation mode\n` +
     `\`/revela designs\`             — list installed designs\n` +
     `\`/revela designs <name>\`      — activate a design\n` +
+    `\`/revela designs-new <name>\`  — create a new custom design with AI\n` +
+    `\`/revela designs-edit <name>\` — refine an existing custom design with AI\n` +
+    `\`/revela designs-preview [name]\` — open a design preview in browser\n` +
     `\`/revela domains\`             — list installed domains\n` +
     `\`/revela domains <name>\`      — activate a domain\n` +
     `\`/revela designs-add <url>\`   — install a design from URL / github:user/repo\n` +

package/lib/design/designs.ts

@@ -39,9 +39,51 @@ export interface DesignInfo {
   description: string
   author: string
   version: string
+  internal: boolean
   skillText: string
 }
 
+export interface ListDesignsOptions {
+  includeInternal?: boolean
+}
+
+export interface CreateDesignPackageArgs {
+  name: string
+  base?: string
+  designMd: string
+  previewHtml: string
+  overwrite?: boolean
+}
+
+export interface CreateDesignPackageResult {
+  ok: true
+  name: string
+  path: string
+  files: string[]
+  base?: string
+  overwritten: boolean
+}
+
+export interface ValidateDesignPackageResult {
+  ok: boolean
+  name: string
+  path: string
+  hasDesignMd: boolean
+  hasPreview: boolean
+  hasMarkers: boolean
+  sections: string[]
+  layouts: string[]
+  components: string[]
+  errors: string[]
+}
+
+export interface DesignPreviewInfo {
+  name: string
+  designDir: string
+  previewPath: string
+  hasPreview: boolean
+}
+
 // ---------------------------------------------------------------------------
 // Seed
 // ---------------------------------------------------------------------------
@@ -80,6 +122,7 @@ export function parseDesignFile(filePath: string): DesignInfo | null {
       description: meta.description || "",
       author: meta.author || "unknown",
       version: meta.version || "0.0.0",
+      internal: meta.internal === "true",
       skillText: body,
     }
   } catch (e) {
@@ -95,10 +138,11 @@ export function parseDesignFile(filePath: string): DesignInfo | null {
 // Public API
 // ---------------------------------------------------------------------------
 
-/** List all installed designs, sorted by name. */
-export function listDesigns(): DesignInfo[] {
+/** List installed designs, sorted by name. Internal designs are hidden by default. */
+export function listDesigns(options: ListDesignsOptions = {}): DesignInfo[] {
   if (!existsSync(DESIGNS_DIR)) return []
   const results: DesignInfo[] = []
+  const includeInternal = options.includeInternal ?? false
 
   for (const entry of readdirSync(DESIGNS_DIR).sort()) {
     const dir = join(DESIGNS_DIR, entry)
@@ -106,7 +150,7 @@ export function listDesigns(): DesignInfo[] {
     const mdPath = join(dir, "DESIGN.md")
     if (!existsSync(mdPath)) continue
     const info = parseDesignFile(mdPath)
-    if (info) results.push(info)
+    if (info && (includeInternal || !info.internal)) results.push(info)
   }
   return results
 }
@@ -141,6 +185,135 @@ export function getDesignSkillMd(name?: string): string {
   return info.skillText
 }
 
+/** Resolve a design's preview.html path. Throws if the design is not installed. */
+export function resolveDesignPreview(name?: string): DesignPreviewInfo {
+  const designName = normalizeDesignName(name || activeDesign())
+  const designDir = join(DESIGNS_DIR, designName)
+  const mdPath = join(designDir, "DESIGN.md")
+  if (!existsSync(designDir) || !existsSync(mdPath)) {
+    throw new Error(`Design '${designName}' is not installed`)
+  }
+
+  const previewPath = join(designDir, "preview.html")
+  return {
+    name: designName,
+    designDir,
+    previewPath,
+    hasPreview: existsSync(previewPath),
+  }
+}
+
+/** Normalize and validate a design package name. */
+export function normalizeDesignName(name: string): string {
+  const normalized = name.trim().toLowerCase()
+  if (!/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(normalized)) {
+    throw new Error("Design name must be kebab-case using lowercase letters, numbers, and hyphens")
+  }
+  return normalized
+}
+
+/** Create a local design package in ~/.config/revela/designs/<name>/. */
+export function createDesignPackage(args: CreateDesignPackageArgs): CreateDesignPackageResult {
+  const name = normalizeDesignName(args.name)
+  const designMd = args.designMd?.trim()
+  const previewHtml = args.previewHtml?.trim()
+
+  if (!designMd) throw new Error("designMd is required")
+  if (!previewHtml) throw new Error("previewHtml is required")
+
+  const target = join(DESIGNS_DIR, name)
+  const existed = existsSync(target)
+  if (existed && !args.overwrite) {
+    throw new Error(`Design '${name}' already exists. Pass overwrite=true to replace it.`)
+  }
+
+  mkdirSync(DESIGNS_DIR, { recursive: true })
+  if (existed) {
+    rmSync(target, { recursive: true, force: true })
+  }
+  mkdirSync(target, { recursive: true })
+  writeFileSync(join(target, "DESIGN.md"), `${designMd}\n`, "utf-8")
+  writeFileSync(join(target, "preview.html"), `${previewHtml}\n`, "utf-8")
+
+  const validation = validateDesignPackage(name)
+  if (!validation.ok) {
+    throw new Error(`Created design package is invalid: ${validation.errors.join("; ")}`)
+  }
+
+  return {
+    ok: true,
+    name,
+    path: target,
+    files: ["DESIGN.md", "preview.html"],
+    base: args.base,
+    overwritten: existed,
+  }
+}
+
+/** Validate a local design package for the minimum Revela design contract. */
+export function validateDesignPackage(nameInput: string): ValidateDesignPackageResult {
+  let name = nameInput
+  const errors: string[] = []
+  try {
+    name = normalizeDesignName(nameInput)
+  } catch (e) {
+    errors.push(e instanceof Error ? e.message : String(e))
+  }
+
+  const dir = join(DESIGNS_DIR, name)
+  const mdPath = join(dir, "DESIGN.md")
+  const previewPath = join(dir, "preview.html")
+  const hasDesignMd = existsSync(mdPath)
+  const hasPreview = existsSync(previewPath)
+  let hasMarkers = false
+  let sections: string[] = []
+  let layouts: string[] = []
+  let components: string[] = []
+
+  if (!existsSync(dir)) errors.push(`Design directory does not exist: ${dir}`)
+  if (!hasDesignMd) errors.push("DESIGN.md is missing")
+  if (!hasPreview) errors.push("preview.html is missing")
+
+  if (hasDesignMd) {
+    const info = parseDesignFile(mdPath)
+    if (!info) {
+      errors.push("DESIGN.md could not be parsed")
+    } else {
+      const parsed = parseDesignSections(info.skillText)
+      hasMarkers = parsed.hasMarkers
+      sections = Object.keys(parsed.sections)
+      layouts = Object.keys(parsed.layouts)
+      components = Object.keys(parsed.components)
+
+      if (!hasMarkers) errors.push("DESIGN.md must include marker sections")
+      if (!parsed.sections.foundation) errors.push("@design:foundation section is missing")
+      if (!parsed.sections.rules) errors.push("@design:rules section is missing")
+      if (layouts.length === 0) errors.push("At least one @layout section is required")
+      if (components.length === 0) errors.push("At least one @component section is required")
+    }
+  }
+
+  if (hasPreview) {
+    const preview = readFileSync(previewPath, "utf-8")
+    if (!preview.includes('<section class="slide"')) errors.push("preview.html must include slide sections")
+    if (!preview.includes("slide-qa=")) errors.push("preview.html slides must include slide-qa attributes")
+    if (!preview.includes("slide-canvas")) errors.push("preview.html must include .slide-canvas")
+  }
+
+  return {
+    ok: errors.length === 0,
+    name,
+    path: dir,
+    hasDesignMd,
+    hasPreview,
+    hasMarkers,
+    sections,
+    layouts,
+    components,
+    errors,
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Marker-based section / component parsing
 // ---------------------------------------------------------------------------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyber-dash-tech/revela",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "OpenCode plugin that turns AI into an HTML slide deck generator",
   "type": "module",
   "main": "./index.ts",
@@ -13,8 +13,12 @@
     "tools/",
     "skill/",
     "designs/aurora/DESIGN.md",
+    "designs/starter/DESIGN.md",
+    "designs/starter/preview.html",
     "designs/summit/DESIGN.md",
+    "designs/summit/preview.html",
     "designs/monet/DESIGN.md",
+    "designs/monet/preview.html",
     "domains/general/INDUSTRY.md",
     "domains/deeptech-investment/INDUSTRY.md",
     "domains/consulting/INDUSTRY.md",

package/plugin.ts

@@ -45,6 +45,14 @@ import {
 } from "./lib/commands/domains"
 import { handlePdf } from "./lib/commands/pdf"
 import { handlePptx } from "./lib/commands/pptx"
+import { handleDesignsPreview } from "./lib/commands/designs-preview"
+import {
+  parseDesignsNewArgs,
+  buildDesignsNewPrompt,
+  parseDesignsEditArgs,
+  buildDesignsEditPrompt,
+} from "./lib/commands/designs-new"
+import designsAuthorTool from "./tools/designs-author"
 import designsTool from "./tools/designs"
 import domainsTool from "./tools/domains"
 import mediaBatchSaveTool from "./tools/media-batch-save"
@@ -203,6 +211,36 @@ const server: Plugin = (async (pluginCtx) => {
         await handleDesignsAdd(param, send)
         throw new Error("__REVELA_DESIGNS_ADD_HANDLED__")
       }
+      if (sub === "designs-new") {
+        const parsed = parseDesignsNewArgs(param)
+        if (!parsed.ok) {
+          await send(parsed.error)
+          throw new Error("__REVELA_DESIGNS_NEW_USAGE_HANDLED__")
+        }
+        output.parts.length = 0
+        output.parts.push({
+          type: "text",
+          text: buildDesignsNewPrompt({ name: parsed.name, base: parsed.base }),
+        } as any)
+        return
+      }
+      if (sub === "designs-edit") {
+        const parsed = parseDesignsEditArgs(param)
+        if (!parsed.ok) {
+          await send(parsed.error)
+          throw new Error("__REVELA_DESIGNS_EDIT_USAGE_HANDLED__")
+        }
+        output.parts.length = 0
+        output.parts.push({
+          type: "text",
+          text: buildDesignsEditPrompt({ name: parsed.name }),
+        } as any)
+        return
+      }
+      if (sub === "designs-preview") {
+        await handleDesignsPreview(param, send)
+        throw new Error("__REVELA_DESIGNS_PREVIEW_HANDLED__")
+      }
       if (sub === "domains-add") {
         await handleDomainsAdd(param, send)
         throw new Error("__REVELA_DOMAINS_ADD_HANDLED__")
@@ -231,6 +269,7 @@ const server: Plugin = (async (pluginCtx) => {
     // ── LLM tools: designs, domains, research, document materials, qa ─────
     tool: {
       "revela-designs": designsTool,
+      "revela-designs-author": designsAuthorTool,
       "revela-domains": domainsTool,
       "revela-media-batch-save": mediaBatchSaveTool,
       "revela-media-save": mediaSaveTool,

package/tools/designs-author.ts

@@ -0,0 +1,62 @@
+import { tool } from "@opencode-ai/plugin"
+import { createDesignPackage, validateDesignPackage } from "../lib/design/designs"
+
+export default tool({
+  description:
+    "Create and validate local Revela design packages generated by the AI design authoring workflow. " +
+    "Use action 'create' to save DESIGN.md and preview.html into ~/.config/revela/designs/{name}/. " +
+    "Use action 'validate' to check a generated design package before asking the user to activate it.",
+  args: {
+    action: tool.schema
+      .enum(["create", "validate"])
+      .describe("Operation to perform"),
+    name: tool.schema
+      .string()
+      .optional()
+      .describe("Design name in kebab-case. Required for create and validate."),
+    base: tool.schema
+      .string()
+      .optional()
+      .describe("Base design used as structural scaffold, e.g. 'summit'. Recorded in the result only."),
+    designMd: tool.schema
+      .string()
+      .optional()
+      .describe("Complete DESIGN.md content. Required for create."),
+    previewHtml: tool.schema
+      .string()
+      .optional()
+      .describe("Complete preview.html content. Required for create."),
+    overwrite: tool.schema
+      .boolean()
+      .optional()
+      .describe("Whether to replace an existing local design package. Defaults to false."),
+  },
+  async execute(args) {
+    try {
+      if (!args.name) return JSON.stringify({ error: "name is required" })
+
+      switch (args.action) {
+        case "create": {
+          if (!args.designMd) return JSON.stringify({ error: "designMd is required for create" })
+          if (!args.previewHtml) return JSON.stringify({ error: "previewHtml is required for create" })
+          const result = createDesignPackage({
+            name: args.name,
+            base: args.base,
+            designMd: args.designMd,
+            previewHtml: args.previewHtml,
+            overwrite: args.overwrite ?? false,
+          })
+          return JSON.stringify(result, null, 2)
+        }
+        case "validate": {
+          return JSON.stringify(validateDesignPackage(args.name), null, 2)
+        }
+        default: {
+          return JSON.stringify({ error: `Unknown action: ${args.action}` })
+        }
+      }
+    } catch (e: any) {
+      return JSON.stringify({ error: e.message || String(e) })
+    }
+  },
+})