@cyber-dash-tech/revela 0.17.18 → 0.17.21

package/README.md

@@ -34,7 +34,7 @@ To install globally, add the same entry to `~/.config/opencode/opencode.json`.
 Requirements:
 
 - The Codex CLI must be installed and the `codex` command must be available in your shell.
-- Your environment must be able to run `npx`; Revela uses `npx -y @cyber-dash-tech/revela@0.17.12 mcp` to start the MCP server.
+- Your environment must be able to run `npx`; Revela uses `npx -y @cyber-dash-tech/revela@0.17.21 mcp` to start the MCP server.
 - For interactive Review actions, `codex exec` must also work because the Review UI uses it for Insight and Comment/Apply Fix requests.
 
 Optional preflight:
@@ -55,11 +55,11 @@ npm_config_cache=/tmp/revela-npm-cache bun run smoke:mcp-pack
 Install Revela through the Codex Git marketplace:
 
 ```bash
-codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.17.12
+codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.17.21
 codex plugin add revela@revela
 ```
 
-The Git marketplace install provides the Codex plugin shell, skills, hooks, and MCP configuration. When Codex starts the Revela MCP server for the first time, it runs `npx -y @cyber-dash-tech/revela@0.17.12 mcp` so npm can fetch the published package and its dependencies.
+The Git marketplace install provides the Codex plugin shell, skills, hooks, and MCP configuration. When Codex starts the Revela MCP server for the first time, it runs `npx -y @cyber-dash-tech/revela@0.17.21 mcp` so npm can fetch the published package and its dependencies.
 
 You do not need to run `bun install` inside the Codex marketplace clone.
 
@@ -67,6 +67,28 @@ Start a new Codex thread after installing so Codex loads the Revela skills, MCP
 
 For release-aligned local validation, run `bun run smoke:mcp-pack`. It packs the current checkout to a temporary npm tarball and starts the MCP server through `npx`, matching the published Codex launcher path without requiring a registry publish.
 
+#### Codex Upgrade
+
+In Codex, ask Revela to check the current runtime version; the plugin calls `revela_doctor` and reports the running `version`.
+
+For a fixed release tag, reinstall the plugin from that tag:
+
+```bash
+codex plugin remove revela@revela
+codex plugin marketplace remove revela
+codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref vX.Y.Z
+codex plugin add revela@revela
+```
+
+For a marketplace entry that intentionally tracks a branch or movable ref, upgrade the marketplace clone and re-add the plugin:
+
+```bash
+codex plugin marketplace upgrade revela
+codex plugin add revela@revela
+```
+
+The Git marketplace ref and `.mcp.json` npm pin are part of the same release artifact. Start a new Codex thread after upgrading so Codex reloads the Revela skills, MCP tools, hooks, and runtime pin.
+
 ## Built-In Designs
 
 Revela includes built-in deck designs:

package/README.zh-CN.md

@@ -34,7 +34,7 @@ Revela 可在 [OpenCode](https://opencode.ai) 和 Codex 中使用，把来源材
 环境要求：
 
 - 需要已安装 Codex CLI，并且 shell 中可以执行 `codex`。
-- 环境中需要可以执行 `npx`；Revela 会用 `npx -y @cyber-dash-tech/revela@0.17.12 mcp` 启动 MCP server。
+- 环境中需要可以执行 `npx`；Revela 会用 `npx -y @cyber-dash-tech/revela@0.17.21 mcp` 启动 MCP server。
 - 如果使用 Review UI 的 Insight、Comment 或 Apply Fix，需要 `codex exec` 可用。
 
 可选的安装前检查：
@@ -55,11 +55,11 @@ npm_config_cache=/tmp/revela-npm-cache bun run smoke:mcp-pack
 通过 Codex Git marketplace 安装 Revela：
 
 ```bash
-codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.17.12
+codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.17.21
 codex plugin add revela@revela
 ```
 
-Git marketplace 安装的是 Codex plugin 壳、skills、hooks 和 MCP 配置。Codex 第一次启动 Revela MCP server 时，会运行 `npx -y @cyber-dash-tech/revela@0.17.12 mcp`，由 npm 获取已发布 package 及其 dependencies。
+Git marketplace 安装的是 Codex plugin 壳、skills、hooks 和 MCP 配置。Codex 第一次启动 Revela MCP server 时，会运行 `npx -y @cyber-dash-tech/revela@0.17.21 mcp`，由 npm 获取已发布 package 及其 dependencies。
 
 不需要在 Codex marketplace clone 里运行 `bun install`。
 
@@ -67,6 +67,28 @@ Git marketplace 安装的是 Codex plugin 壳、skills、hooks 和 MCP 配置。
 
 如果要按发布路径做本地验证，运行 `bun run smoke:mcp-pack`。它会把当前 checkout 打成临时 npm tarball，再通过 `npx` 启动 MCP server，不需要先发布到 registry。
 
+#### Codex 升级
+
+在 Codex 中，可以让 Revela 检查当前 runtime version；plugin 会调用 `revela_doctor` 并报告正在运行的 `version`。
+
+如果要固定到某个 release tag，按该 tag 重新安装 plugin：
+
+```bash
+codex plugin remove revela@revela
+codex plugin marketplace remove revela
+codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref vX.Y.Z
+codex plugin add revela@revela
+```
+
+如果 marketplace entry 本来就有意跟踪 branch 或 movable ref，升级 marketplace clone 后重新添加 plugin：
+
+```bash
+codex plugin marketplace upgrade revela
+codex plugin add revela@revela
+```
+
+Git marketplace ref 和 `.mcp.json` npm pin 属于同一个 release artifact。升级后开启一个新的 Codex thread，让 Codex 重新加载 Revela skills、MCP tools、hooks 和 runtime pin。
+
 ## 内置设计
 
 Revela 内置多个 deck design：

package/designs/monet/DESIGN.md

@@ -480,6 +480,8 @@ These rules are mandatory for Monet.
 - **Sparse slides depend on image weight.** If content is light, the photo or page framing must hold the composition.
 - **No glass cards, neon KPI styling, or startup-product chrome.** Monet is editorial and print-adjacent.
 - **Visual hierarchy is strict:** eyebrow -> heading -> body -> caption.
+- **Content pages need a stable title block.** Except cover, TOC, closing, section divider, and full-bleed hero slides, every normal content slide should include a visible slide-level title block from the upper-left safe area. It should contain a compact chapter/section label plus a slide title written as the page's claim or takeaway.
+- **Do not hide the page title inside a component.** Body components may have their own headings, but `text-panel`, `box`, `toc`, chart/table headers, and editorial module headings do not replace the slide-level title block.
 - **Icon system is Lucide.** For ordinary UI, semantic, status, category, process, and navigation icons, use Lucide (`data-lucide`). Do not hand-write inline SVG for icons. SVG is allowed only for intentional decorative motifs, illustrations, or design-specific artwork. If any `data-lucide` icon is present, load Lucide via CDN and call `lucide.createIcons()` after `SlidePresentation`.
 - **Chart system is ECharts.** Data charts default to ECharts inside `echart-panel`. Do not use hand-written SVG, div/CSS shapes, canvas mocks, or static faux charts as data-chart substitutes. SVG remains acceptable for decorative motifs, diagrams, or illustrations, not data charts. Before creating or changing a chart, fetch the `echart-panel` component and `section: "chart-rules"`; if chart rules or runtime are unavailable, report the gap instead of inventing a fake chart fallback.
 - **Start from foundation.** New deck HTML starts from `@design:foundation`. Do not recreate foundation CSS, JavaScript, or the HTML skeleton from memory. Prefer a foundation helper when available; otherwise fetch `section: "foundation"` before writing a new deck shell. Existing deck edits preserve the current foundation unless the user asks for foundation repair or QA reports a foundation contract problem.
@@ -511,12 +513,14 @@ These rules are mandatory for Monet.
 
 ### Layout Types
 
-Each `<section class="slide">` must set `slide-qa="true"` or `slide-qa="false"`. It must also set `data-slide-index="N"`, where `N` is the canonical positive 1-based artifact slide identity from the approved deck plan or DOM order. Indexes must be unique and strictly increase. Use the QA column to decide which `slide-qa` value to write. Fetch any layout with the `revela-designs` tool (`action: "read"`, `layout: "<name>"`).
+Each `<section class="slide">` must set `slide-qa="true"` or `slide-qa="false"`. It must also set `data-slide-index="N"`, where `N` is the canonical positive 1-based artifact slide identity from the approved deck plan or DOM order. Indexes must be unique and strictly increase. Use the QA column to decide which `slide-qa` value to write. Choose layouts by narrative structure first, not by surface geometry. Fetch any layout with the `revela-designs` tool (`action: "read"`, `layout: "<name>"`).
+
+Normal `qa=true` content layouts must start with a slide-level title block unless the layout marker explicitly says otherwise. Use an eyebrow for chapter/section context, then an `h2` that states the slide's claim or takeaway. Body boxes, charts, media, tables, and text panels should sit below or beside that title region rather than replacing it.
 
 <!-- @layout:fullbleed:start qa=false -->
-#### Fullbleed
+Atmospheric cover, closing, or divider layout with one dominant image-title component.
 
-Full-canvas layout for slides where a single image dominates the entire canvas with text composited over it. Use for opening (cover) and closing slides, or atmospheric section dividers.
+#### Fullbleed
 
 Structural intent:
 - Single slot: place one `image-title` component directly inside `.page`. The component is self-contained — it manages its own image, blur, overlay, and text layers internally.
@@ -542,22 +546,26 @@ Structural intent:
 <!-- @layout:fullbleed:end -->
 
 <!-- @layout:narrative:start qa=true -->
-#### Narrative
+Asymmetric primary-secondary spread with a dominant visual/evidence zone on the left and a narrower explanatory or action zone on the right.
 
-Asymmetric two-column layout with the left column wider (1.618fr) and the right column narrower (1fr). Use when one side needs more visual or reading weight than the other.
+#### Narrative
 
 Structural intent:
-- left slot: wider zone (1.618fr) — can hold any component(s)
-- right slot: narrower zone (1fr) — can hold any component(s)
+- left slot: primary zone (1.618fr) — dominant evidence, image, chart, table, or other high-weight component(s)
+- right slot: secondary zone (1fr) — explanation, implication, action, TOC, vertical flow, or supporting component(s)
 
-Every slot accepts 1 or more components. The LLM decides what each slot contains — there is no text/visual semantic preset.
+Every slot accepts 1 or more components, but the layout should preserve a primary-secondary hierarchy. Do not use `narrative` for two equally weighted items; use `halves` instead.
 
 
 ```html
 <section class="slide" slide-qa="true" data-slide-index="N">
   <div class="slide-canvas">
     <div class="page" style="padding:0;overflow:hidden;">
-      <div class="narrative-grid">
+      <div style="display:flex;flex-direction:column;gap:10px;margin:56px 64px 28px;max-width:760px;position:relative;z-index:2;">
+        <p class="eyebrow">Chapter / Section</p>
+        <h2>Slide claim or takeaway</h2>
+      </div>
+      <div class="narrative-grid" style="height:calc(100% - 150px);">
 
         <!-- [slot: left] — 1+ components; suggested: image-title, echart-panel, text-panel -->
         <div>
@@ -596,28 +604,32 @@ Every slot accepts 1 or more components. The LLM decides what each slot contains
 
 ##### Tips
 - **Grid container uses `.narrative-grid` class.** Applies `minmax(0, Nfr)` tracks, `overflow:hidden` on all children, and `align-items:stretch` so both columns fill the full row height. Do not override with `align-items:start` — that collapses columns to content height and exposes the page background.
-- **No semantic preset.** Either slot can hold any component. The wider left column naturally suits visually dominant content (full-bleed media, wide charts), but this is not a hard rule.
+- **Primary-secondary intent.** The wider left column should carry the stronger visual or evidentiary weight. If both sides are equally important, use `halves`.
 - **Dark panel variant.** When a slot uses a dark background, override CSS variables on that container: `--text-primary`, `--text-secondary`, `--text-muted`, `--line`, `--line-strong` — all set to white-family values. Use `.page-number--light`.
 - **Background image inside a slot.** Use the three-layer z-index pattern: background `z-index:0`, dark overlay `z-index:1`, content `z-index:2`.
 <!-- @layout:narrative:end -->
 
 <!-- @layout:narrative-reverse:start qa=true -->
-#### Narrative Reverse
+Asymmetric primary-secondary spread with the narrower explanatory or action zone on the left and the dominant visual/evidence zone on the right.
 
-Asymmetric two-column layout with the left column narrower (1fr) and the right column wider (1.618fr). Mirror of `narrative` — same grid class with `--reverse` modifier.
+#### Narrative Reverse
 
 Structural intent:
-- left slot: narrower zone (1fr) — can hold any component(s)
-- right slot: wider zone (1.618fr) — can hold any component(s)
+- left slot: secondary zone (1fr) — explanation, implication, action, TOC, vertical flow, or supporting component(s)
+- right slot: primary zone (1.618fr) — dominant evidence, image, chart, table, or other high-weight component(s)
 
-Every slot accepts 1 or more components. The LLM decides what each slot contains — there is no text/visual semantic preset.
+Every slot accepts 1 or more components, but the layout should preserve a primary-secondary hierarchy. Do not use `narrative-reverse` for two equally weighted items; use `halves` instead.
 
 
 ```html
 <section class="slide" slide-qa="true" data-slide-index="N">
   <div class="slide-canvas">
     <div class="page" style="padding:0;overflow:hidden;">
-      <div class="narrative-grid narrative-grid--reverse">
+      <div style="display:flex;flex-direction:column;gap:10px;margin:56px 64px 28px;max-width:760px;position:relative;z-index:2;">
+        <p class="eyebrow">Chapter / Section</p>
+        <h2>Slide claim or takeaway</h2>
+      </div>
+      <div class="narrative-grid narrative-grid--reverse" style="height:calc(100% - 150px);">
 
         <!-- [slot: left] — 1+ components; suggested: text-panel, toc, flow-vertical, echart-panel -->
         <div>
@@ -635,33 +647,33 @@ Every slot accepts 1 or more components. The LLM decides what each slot contains
 
 ##### Tips
 - **Same `.narrative-grid` class as `narrative`, with `--reverse` modifier.** Add both `narrative-grid` and `narrative-grid--reverse` to the grid container. The modifier swaps column proportions to `1fr left / 1.618fr right`.
-- **No semantic preset.** Either slot can hold any component — visual on the right, text on the left, or any other combination based on content needs.
+- **Primary-secondary intent.** The wider right column should carry the stronger visual or evidentiary weight. If both sides are equally important, use `halves`.
 - **Dark panel variant.** Same CSS variable override pattern as `narrative`: set `--text-primary` etc. to white-family values on the panel container, all child components inherit automatically.
 <!-- @layout:narrative-reverse:end -->
 
 <!-- @layout:highlight-cols:start qa=true -->
-#### Highlight Cols
+Parallel 3-5 item spread for comparable proof points, options, features, metrics, or evidence blocks.
 
-Equal N-column layout. Use when 3 or more parallel items of roughly equal visual weight should appear side by side — proof blocks, highlights, feature comparisons, stat groups, or any multi-column editorial spread.
+#### Highlight Cols
 
-A short section header is optional but recommended. In Monet, that header should stay lean: eyebrow plus title only, with no intro paragraph competing with the columns below.
+A short section header is required for normal content uses. In Monet, that header should stay lean: eyebrow plus title only, with no intro paragraph competing with the columns below.
 
 Structural intent:
 - each slot: 1fr column — any component(s)
 - column count: determined by the number of direct child divs in the grid container; `auto-fit` distributes space equally
 
-Every slot accepts 1 or more components. Add or remove child divs to control column count — 3 is the default, but 4 or 5 columns work equally well.
+Every slot accepts 1 or more components. Add or remove child divs to control column count — 3 is the default, but 4 or 5 columns work equally well. Use only for comparable items; do not mix unrelated content types just because the slide needs multiple blocks.
 
 ```html
 <section class="slide" slide-qa="true" data-slide-index="N">
   <div class="slide-canvas">
-    <div class="page">
-      <div style="display:flex;flex-direction:column;gap:10px;margin-bottom:28px;max-width:520px;">
+    <div class="page" style="overflow:hidden;">
+      <div style="display:flex;flex-direction:column;gap:10px;margin:56px 64px 28px;max-width:760px;position:relative;z-index:2;">
         <p class="eyebrow">Section Label</p>
-        <h2 style="font-size:52px;line-height:0.94;text-transform:uppercase;">Short framing title for the parallel columns</h2>
+        <h2 style="font-size:52px;line-height:0.94;text-transform:uppercase;">Slide claim or takeaway</h2>
       </div>
 
-      <div class="highlight-cols-grid" style="flex:1;min-height:0;">
+      <div class="highlight-cols-grid" style="height:calc(100% - 150px);">
 
         <!-- [slot: 1] — 1+ components; suggested: editorial-image-top, editorial-text-top, echart-panel -->
         <div>
@@ -700,28 +712,32 @@ Every slot accepts 1 or more components. Add or remove child divs to control col
 - **Grid container needs `flex:1;min-height:0` inline** when inside `.page` (which is flex-column). The class handles column sizing; the inline style handles row stretch.
 - **Header stays lean.** If you add a section header above the grid, use only `eyebrow + title`. Do not add an intro paragraph; the columns themselves should carry the explanation.
 - **Column count = number of direct child divs.** `repeat(auto-fit, minmax(0, 1fr))` distributes available width equally across however many children exist. Add a 4th or 5th div to get 4 or 5 columns — no CSS change needed.
-- **Equal columns — no hierarchy.** All slots carry the same visual weight. Adjust content density to suit the slide purpose; do not artificially inflate one column to create false hierarchy.
+- **Parallel items only.** All slots carry the same visual weight and should represent the same kind of thing: proof points, options, features, metrics, or evidence blocks.
 - **When using 4-5 columns, compress the header.** Keep the title to one or two short lines so the grid retains most of the slide height.
 - **Do not set fixed heights on editorial components.** Let components fill height via flexbox stretch.
 <!-- @layout:highlight-cols:end -->
 
 <!-- @layout:halves:start qa=true -->
-#### Halves
+Balanced two-up comparison for two equally important items, charts, cases, evidence blocks, or before/after states.
 
-Equal two-column layout. Use when two items of equal visual weight should appear side by side — paired charts, dual evidence blocks, before/after comparisons, or any two-column editorial spread.
+#### Halves
 
 Structural intent:
 - left slot: 1fr column — any component(s)
 - right slot: 1fr column — any component(s)
 
-Every slot accepts 1 or more components. The LLM decides what each slot contains — both columns are fully equal with no hierarchy preset.
+Every slot accepts 1 or more components. Both columns are fully equal by design. Do not use `halves` when one side should dominate; use `narrative` or `narrative-reverse` instead.
 
 
 ```html
 <section class="slide" slide-qa="true" data-slide-index="N">
   <div class="slide-canvas">
     <div class="page" style="overflow:hidden;">
-      <div class="halves-grid" style="flex:1;min-height:0;">
+      <div style="display:flex;flex-direction:column;gap:10px;margin:56px 64px 28px;max-width:760px;position:relative;z-index:2;">
+        <p class="eyebrow">Chapter / Section</p>
+        <h2>Slide claim or takeaway</h2>
+      </div>
+      <div class="halves-grid" style="height:calc(100% - 150px);">
 
         <!-- [slot: left] — 1+ components; suggested: echart-panel, data-table, editorial-image-top -->
         <div>
@@ -755,27 +771,31 @@ Every slot accepts 1 or more components. The LLM decides what each slot contains
 
 ##### Tips
 - **Grid container needs `flex:1;min-height:0` inline** when inside `.page`. The class handles column sizing.
-- **Equal columns — no hierarchy.** Both slots carry the same weight. Choose components based on content, not a fixed text/visual assignment.
+- **Equal columns — no hierarchy.** Both slots carry the same weight. Use this for balanced comparison, not primary-secondary explanation.
 - **Gap `40px` is intentional.** The slightly wider gap than `three-col` (32px) compensates for the larger individual column width.
 <!-- @layout:halves:end -->
 
 <!-- @layout:stacked:start qa=true -->
-#### Stacked
+Top-bottom synthesis layout with compact framing, status, or process context above a larger evidence, table, chart, or detail zone.
 
-Two-row vertical layout in a fixed golden-ratio proportion: top row takes 1fr and bottom row takes 1.618fr. Use when a horizontal component (process flow, stat row, header band) should anchor the top, with a taller content zone below.
+#### Stacked
 
 Structural intent:
-- top slot: `1fr` height — upper zone in golden-ratio proportion
-- bottom slot: `1.618fr` height — larger lower zone fills remaining space
+- top slot: `1fr` height — compact framing, status row, process overview, or synthesis component
+- bottom slot: `1.618fr` height — larger evidence, table, chart, media, or detail component
 
-Every slot accepts 1 or more components. The LLM decides what each slot contains — there is no semantic preset for either row.
+Every slot accepts 1 or more components, but the layout should preserve a synthesis-over-detail relationship. Do not use `stacked` as a generic vertical layout for unrelated blocks.
 
 
 ```html
 <section class="slide" slide-qa="true" data-slide-index="N">
   <div class="slide-canvas">
     <div class="page" style="padding:0;">
-      <div class="stacked-grid">
+      <div style="display:flex;flex-direction:column;gap:10px;margin:56px 64px 28px;max-width:760px;position:relative;z-index:2;">
+        <p class="eyebrow">Chapter / Section</p>
+        <h2>Slide claim or takeaway</h2>
+      </div>
+      <div class="stacked-grid" style="height:calc(100% - 150px);">
 
         <!-- [slot: top] — 1+ components; suggested: flow-horizontal, stat-row -->
         <div class="stacked-top">
@@ -814,7 +834,7 @@ Every slot accepts 1 or more components. The LLM decides what each slot contains
 ##### Tips
 - **Top and bottom rows follow a fixed 1 : 1.618 golden-ratio proportion.** The top slot takes 1fr and the bottom takes 1.618fr — both rows are sized relative to the total canvas height, not by their content.
 - **Both slots clip overflow.** `min-height: 0` on both `.stacked-top` and `.stacked-bottom` ensures content cannot break out of its row.
-- **Both slots are fully equal in kind.** There is no preset for which slot holds "process" vs "data" — place any combination of components that fits the slide narrative.
+- **Synthesis over detail.** The top row should frame or summarize; the bottom row should carry the larger supporting detail.
 - **Dark background variant.** Set CSS variable overrides (`--text-primary` etc.) on `.stacked-grid` to cascade into both slots automatically.
 <!-- @layout:stacked:end -->
 

package/lib/commands/designs-new.ts

@@ -81,6 +81,7 @@ const VISUAL_QUALITY_RULES = `Visual extraction and CSS quality rules:
 
 const PREVIEW_REQUIREMENTS = `Preview requirements:
 - \`preview.html\` must include a cover slide and a closing slide. Mark their \`<section class="slide">\` elements with \`data-slide-role="cover"\` and \`data-slide-role="closing"\`.
+- \`preview.html\` must define an explicit CSS rule for \`.slide-canvas\` with \`width: 1920px\` and \`height: 1080px\`; every direct \`.slide-canvas\` is the fixed 1920px x 1080px export surface.
 - \`preview.html\` must showcase every \`@component:*\` defined in \`DESIGN.md\`. Mark each showcased component with \`data-preview-component="<component-name>"\`.
 - Do not save with \`revela-designs-author\` until every component has a corresponding preview marker. If a component is decorative or abstract, include a visible labeled sample state.
 - When the design supports chart styling, \`preview.html\` should include a 3x3 ECharts gallery with at least 9 chart examples. This is a preview quality requirement, not a validation blocker.`
@@ -133,6 +134,7 @@ Hard requirements:
 - \`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.
+- \`preview.html\` must include an explicit CSS rule: \`.slide-canvas { width: 1920px; height: 1080px; }\`.
 - Every preview slide must include \`slide-qa="true"\` or \`slide-qa="false"\`.
 - \`preview.html\` must include \`data-slide-role="cover"\` and \`data-slide-role="closing"\` on slide sections.
 - \`preview.html\` must showcase every \`@component:*\` with \`data-preview-component="<component-name>"\` before saving.
@@ -172,6 +174,7 @@ 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.
+- \`preview.html\` must include an explicit CSS rule: \`.slide-canvas { width: 1920px; height: 1080px; }\`.
 - Every preview slide must include \`slide-qa="true"\` or \`slide-qa="false"\`.
 - \`preview.html\` must include \`data-slide-role="cover"\` and \`data-slide-role="closing"\` on slide sections.
 - \`preview.html\` must showcase every \`@component:*\` with \`data-preview-component="<component-name>"\` before saving.

package/lib/design/designs.ts

@@ -18,7 +18,7 @@ import {
   statSync,
   writeFileSync,
 } from "fs"
-import { join, resolve, basename } from "path"
+import { dirname, join, resolve, basename } from "path"
 import { tmpdir } from "os"
 import { parseFrontmatter } from "../frontmatter"
 import {
@@ -55,6 +55,10 @@ export interface CreateDesignPackageArgs {
   overwrite?: boolean
 }
 
+export interface CreateDesignDraftArgs extends CreateDesignPackageArgs {
+  workspaceRoot: string
+}
+
 export interface CreateDesignPackageResult {
   ok: true
   name: string
@@ -64,6 +68,16 @@ export interface CreateDesignPackageResult {
   overwritten: boolean
 }
 
+export interface InstallDesignDraftArgs {
+  workspaceRoot: string
+  name: string
+  overwrite?: boolean
+}
+
+export interface InstallDesignDraftResult extends CreateDesignPackageResult {
+  sourcePath: string
+}
+
 export interface ValidateDesignPackageResult {
   ok: boolean
   name: string
@@ -250,6 +264,90 @@ export function createDesignPackage(args: CreateDesignPackageArgs): CreateDesign
   }
 }
 
+/** Create a project-local design draft under .revela/drafts/designs/<name>/. */
+export function createDesignDraftPackage(args: CreateDesignDraftArgs): 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 = designDraftDir(args.workspaceRoot, name)
+  const existed = existsSync(target)
+  if (existed && !args.overwrite) {
+    throw new Error(`Design draft '${name}' already exists. Pass overwrite=true to replace it.`)
+  }
+
+  mkdirSync(dirname(target), { 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 = validateDesignDraftPackage(args.workspaceRoot, name)
+  if (!validation.ok) {
+    throw new Error(`Created design draft is invalid: ${validation.errors.join("; ")}`)
+  }
+
+  return {
+    ok: true,
+    name,
+    path: target,
+    files: ["DESIGN.md", "preview.html"],
+    base: args.base,
+    overwritten: existed,
+  }
+}
+
+/** Validate a project-local design draft. */
+export function validateDesignDraftPackage(workspaceRoot: string, nameInput: string): ValidateDesignPackageResult {
+  let name = nameInput
+  try {
+    name = normalizeDesignName(nameInput)
+  } catch {
+    // validateDesignPackageAt records the invalid-name error.
+  }
+  return validateDesignPackageAt(nameInput, designDraftDir(workspaceRoot, name))
+}
+
+/** Install a validated project-local design draft into the user-level design registry. */
+export function installDesignDraftPackage(args: InstallDesignDraftArgs): InstallDesignDraftResult {
+  const name = normalizeDesignName(args.name)
+  const sourcePath = designDraftDir(args.workspaceRoot, name)
+  const validation = validateDesignDraftPackage(args.workspaceRoot, name)
+  if (!validation.ok) {
+    throw new Error(`Design draft is invalid: ${validation.errors.join("; ")}`)
+  }
+
+  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.`)
+  }
+
+  try {
+    mkdirSync(DESIGNS_DIR, { recursive: true })
+    if (existed) {
+      rmSync(target, { recursive: true, force: true })
+    }
+    cpSync(sourcePath, target, { recursive: true })
+  } catch (e) {
+    throw new Error(`Installing design draft requires write access to Revela user config at ${DESIGNS_DIR}: ${e instanceof Error ? e.message : String(e)}`)
+  }
+
+  return {
+    ok: true,
+    name,
+    path: target,
+    sourcePath,
+    files: ["DESIGN.md", "preview.html"],
+    overwritten: existed,
+  }
+}
+
 function hasDataAttribute(html: string, attr: string, value: string): boolean {
   const escaped = value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
   return new RegExp(`${attr}\\s*=\\s*(["'])${escaped}\\1`).test(html)
@@ -264,8 +362,41 @@ function hasSlideRole(html: string, role: string): boolean {
   return false
 }
 
+function cssRuleHasClassSelector(selectors: string, className: string): boolean {
+  const escaped = className.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+  return new RegExp(`(^|[^a-zA-Z0-9_-])\\.${escaped}(?![a-zA-Z0-9_-])`).test(selectors)
+}
+
+function cssRuleHasFixedCanvasSize(body: string): boolean {
+  const width = /(?:^|[;\s])width\s*:\s*1920px(?:\s*!important)?\s*(?:;|$)/i.test(body)
+  const height = /(?:^|[;\s])height\s*:\s*1080px(?:\s*!important)?\s*(?:;|$)/i.test(body)
+  return width && height
+}
+
+function hasFixedSizeCssRule(html: string, className: "slide-canvas"): boolean {
+  const withoutComments = html.replace(/\/\*[\s\S]*?\*\//g, "")
+  const ruleRe = /([^{}]+)\{([^{}]+)\}/g
+  let match: RegExpExecArray | null
+  while ((match = ruleRe.exec(withoutComments)) !== null) {
+    if (cssRuleHasClassSelector(match[1] ?? "", className) && cssRuleHasFixedCanvasSize(match[2] ?? "")) {
+      return true
+    }
+  }
+  return false
+}
+
 /** Validate a local design package for the minimum Revela design contract. */
 export function validateDesignPackage(nameInput: string): ValidateDesignPackageResult {
+  let name = nameInput
+  try {
+    name = normalizeDesignName(nameInput)
+  } catch {
+    // validateDesignPackageAt records the invalid-name error.
+  }
+  return validateDesignPackageAt(nameInput, join(DESIGNS_DIR, name))
+}
+
+function validateDesignPackageAt(nameInput: string, dir: string): ValidateDesignPackageResult {
   let name = nameInput
   const errors: string[] = []
   try {
@@ -274,7 +405,6 @@ export function validateDesignPackage(nameInput: string): ValidateDesignPackageR
     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)
@@ -312,6 +442,9 @@ export function validateDesignPackage(nameInput: string): ValidateDesignPackageR
     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")
+    if (!hasFixedSizeCssRule(preview, "slide-canvas")) {
+      errors.push("preview.html must define .slide-canvas CSS with width: 1920px and height: 1080px")
+    }
     if (!hasSlideRole(preview, "cover")) errors.push('preview.html must include a slide section with data-slide-role="cover"')
     if (!hasSlideRole(preview, "closing")) errors.push('preview.html must include a slide section with data-slide-role="closing"')
     const missingComponents = components.filter((component) => !hasDataAttribute(preview, "data-preview-component", component))
@@ -334,6 +467,10 @@ export function validateDesignPackage(nameInput: string): ValidateDesignPackageR
   }
 }
 
+function designDraftDir(workspaceRoot: string, name: string): string {
+  return resolve(workspaceRoot, ".revela", "drafts", "designs", name)
+}
+
 // ---------------------------------------------------------------------------
 // Marker-based section / component parsing
 // ---------------------------------------------------------------------------