voxflow 1.15.0 → 1.15.2

package/lib/internal/slice-themes.json

@@ -0,0 +1,370 @@
+{
+  "$comment": "Single source of truth for Slice visual themes. Consumed by backend (deck-validator / composition-core schemas / render-worker pipeline / slicing prompt), CLI (slice + slice-stage commands), and apps/console (SLICE_THEMES UI metadata). Adding a theme: append an entry here. The Remotion <Composition>/<Still> in video-present/src/Root.tsx + matching CSS blocks in apps/console/app/apps/slice/three-col.css still need authoring, but ID + metadata + dispatch live here. The completeness test (apps/console/lib/slice/__tests__/theme-registry-coverage.test.ts) fails build if you forget either. Optional `variants[]` describes palette swaps within a theme; each variant has its own id/label/accent for UI chips. Default variant = variants[0] or theme-level palette when absent.",
+  "default": "paper-slide",
+  "themes": [
+    {
+      "id": "paper-slide",
+      "label": "纸面",
+      "blurb": "泛黄纸纹 · 衬线红字 · 手绘印章",
+      "accent": "#7a1f15",
+      "platforms": ["抖音", "视频号", "小红书"],
+      "remotion": { "deck": "PaperSlideDeck", "cover": "PaperSlide-Cover" },
+      "variants": [
+        { "id": "classic", "label": "经典朱红", "accent": "#7a1f15" },
+        { "id": "forest", "label": "深林墨绿", "accent": "#1e4d33" },
+        { "id": "ocean", "label": "深海靛蓝", "accent": "#1a3a5c" }
+      ]
+    },
+    {
+      "id": "editorial-mag",
+      "label": "编辑刊",
+      "blurb": "米白页面 · 衬线斜体 · 杂志感留白",
+      "accent": "#6b1a1a",
+      "platforms": ["知乎", "公众号", "Linkedin"],
+      "remotion": { "deck": "EditorialMagDeck", "cover": "EditorialMag-Cover" },
+      "variants": [
+        { "id": "cream", "label": "经典米白", "accent": "#6b1a1a" },
+        { "id": "sepia", "label": "棕褐古典", "accent": "#9a4b1a" },
+        { "id": "cold-grey", "label": "冷调灰蓝", "accent": "#1b4f5c" }
+      ]
+    },
+    {
+      "id": "bold-poster",
+      "label": "大字海报",
+      "blurb": "左侧 accent · 黑体粗字 · 数字大块",
+      "accent": "#FF3B30",
+      "platforms": ["X", "Threads", "Linkedin"],
+      "remotion": { "deck": "BoldPosterDeck", "cover": "BoldPoster-Cover" },
+      "variants": [
+        { "id": "vermilion", "label": "经典朱红", "accent": "#FF3B30" },
+        { "id": "electric", "label": "电光蓝", "accent": "#0066ff" },
+        { "id": "forest", "label": "深林绿", "accent": "#1f8a3a" }
+      ]
+    },
+    {
+      "id": "notion-card",
+      "label": "Notion 卡",
+      "blurb": "纯白底 · 暖灰墨 · 蓝色 accent · 页面图标",
+      "accent": "#0066ff",
+      "platforms": ["公众号", "飞书", "知识星球"],
+      "remotion": { "deck": "NotionCardDeck", "cover": "NotionCard-Cover" },
+      "variants": [
+        { "id": "signal", "label": "信号蓝", "accent": "#0066ff" },
+        { "id": "peach", "label": "暖橘桃", "accent": "#ec8854" },
+        { "id": "sage", "label": "宁静鼠尾", "accent": "#5e9b7a" }
+      ]
+    },
+    {
+      "id": "brutalist",
+      "label": "粗野",
+      "blurb": "黑白纯色 · 粗边框 · NO.NN 标签 · raw 排版",
+      "accent": "#000000",
+      "platforms": ["X", "Mastodon", "播客"],
+      "remotion": { "deck": "BrutalistDeck", "cover": "Brutalist-Cover" }
+    },
+    {
+      "id": "glass-dark",
+      "label": "玻璃夜",
+      "blurb": "深色渐变 · 紫色发光 · 玻璃拟态 · 短视频感",
+      "accent": "#a855f7",
+      "platforms": ["抖音", "视频号", "TikTok"],
+      "remotion": { "deck": "GlassDarkDeck", "cover": "GlassDark-Cover" },
+      "variants": [
+        { "id": "violet", "label": "电光紫", "accent": "#a855f7" },
+        { "id": "ember", "label": "暖琥珀", "accent": "#ff9844" },
+        { "id": "aqua", "label": "霓虹青", "accent": "#5fd6e0" }
+      ]
+    },
+    {
+      "id": "broadsheet",
+      "label": "财经刊",
+      "blurb": "FT 三文鱼底 · 重磅衬线 · 首字下沉 · DATELINE 红标",
+      "accent": "#0c2e5b",
+      "platforms": ["LinkedIn", "知乎", "雪球"],
+      "remotion": { "deck": "BroadsheetDeck", "cover": "Broadsheet-Cover" },
+      "variants": [
+        { "id": "salmon", "label": "FT 三文鱼", "accent": "#0c2e5b" },
+        { "id": "cream", "label": "周末刊奶白", "accent": "#1e3a5c" },
+        { "id": "editorial-grey", "label": "现代冷灰", "accent": "#0a1428" }
+      ]
+    },
+    {
+      "id": "blueprint",
+      "label": "蓝晒图",
+      "blurb": "青底 + 白色网格 · 橙色尺寸标 · 工程图纸感",
+      "accent": "#ffb74a",
+      "platforms": ["少数派", "知乎", "GitHub"],
+      "remotion": { "deck": "BlueprintDeck", "cover": "Blueprint-Cover" },
+      "variants": [
+        { "id": "cyanotype", "label": "经典蓝晒", "accent": "#ffb74a" },
+        { "id": "redline", "label": "评审红线", "accent": "#e74c3c" },
+        { "id": "nightshift", "label": "夜班加深", "accent": "#ffd97a" }
+      ]
+    },
+    {
+      "id": "daisy-pastel",
+      "label": "雏菊",
+      "blurb": "奶油底 + 手绘雏菊 + 星星 · 粉嫩可爱",
+      "accent": "#e58a9c",
+      "platforms": ["小红书", "微博", "即刻"],
+      "remotion": { "deck": "DaisyPastelDeck", "cover": "DaisyPastel-Cover" },
+      "variants": [
+        { "id": "petal", "label": "粉嫩花瓣", "accent": "#e58a9c" },
+        { "id": "meadow", "label": "草地鼠尾草", "accent": "#7ea876" },
+        { "id": "sunset", "label": "夕阳珊瑚", "accent": "#e8957a" }
+      ]
+    },
+    {
+      "id": "showa-catalog",
+      "label": "昭和目录",
+      "blurb": "70s city-pop · 彩色圆堆 + 彩虹斜条 + 太阳印章",
+      "accent": "#d6437b",
+      "platforms": ["小红书", "B 站", "播客"],
+      "remotion": { "deck": "ShowaCatalogDeck", "cover": "ShowaCatalog-Cover" },
+      "variants": [
+        { "id": "pop", "label": "城市流行", "accent": "#d6437b" },
+        { "id": "pastel", "label": "indie zine 软调", "accent": "#e0a4b8" },
+        { "id": "monochrome", "label": "复古单色", "accent": "#a04030" }
+      ]
+    },
+    {
+      "id": "photo-feature",
+      "label": "摄影刊",
+      "blurb": "全屏摄影 + 渐变压底 + 重磅衬线 · 旅行游记感",
+      "accent": "#e8b455",
+      "platforms": ["小红书", "知乎", "微博"],
+      "remotion": { "deck": "PhotoFeatureDeck", "cover": "PhotoFeature-Cover" },
+      "variants": [
+        { "id": "warm-amber", "label": "暖琥珀夕照", "accent": "#e8b455" },
+        { "id": "cool-blue", "label": "冷调暮色", "accent": "#7ecbe8" },
+        { "id": "monochrome", "label": "黑白纪实", "accent": "#cccccc" }
+      ]
+    },
+    {
+      "id": "atmospheric",
+      "label": "深夜刊",
+      "blurb": "黑底 + 一束暖光 + 衬线粉红 italic · 深夜散文",
+      "accent": "#dd5878",
+      "platforms": ["微博", "即刻", "播客"],
+      "remotion": { "deck": "AtmosphericDeck", "cover": "Atmospheric-Cover" }
+    },
+    {
+      "id": "art-mag",
+      "label": "艺术杂志",
+      "blurb": "颗粒感色块 + 大字衬线 · 几何球 · 艺术画廊感",
+      "accent": "#dd5e72",
+      "platforms": ["小红书", "播客", "即刻"],
+      "remotion": { "deck": "ArtMagDeck", "cover": "ArtMag-Cover" },
+      "variants": [
+        { "id": "vivid", "label": "高彩编辑", "accent": "#dd5e72" },
+        { "id": "muted", "label": "莫兰迪低饱和", "accent": "#c08488" },
+        { "id": "bauhaus", "label": "包豪斯三原色", "accent": "#c8242c" }
+      ]
+    },
+    {
+      "id": "tome-noir",
+      "label": "夜灯",
+      "blurb": "纯黑 + humanist sans · 60/40 非对称 · 暖光晕",
+      "accent": "#ffb38a",
+      "platforms": ["X", "LinkedIn", "即刻"],
+      "remotion": { "deck": "TomeNoirDeck", "cover": "TomeNoir-Cover" },
+      "variants": [
+        { "id": "noir", "label": "暖琥珀", "accent": "#ffb38a" },
+        { "id": "bronze", "label": "古铜", "accent": "#c0744a" },
+        { "id": "platinum", "label": "冷银", "accent": "#a8b0bd" }
+      ]
+    },
+    {
+      "id": "flomo-mute",
+      "label": "纯白",
+      "blurb": "#fafafa Muji 纸面 · IBM Plex + 苹方 · 绿色细线 · 零装饰",
+      "accent": "#4ea870",
+      "platforms": ["小红书", "即刻", "微博"],
+      "remotion": { "deck": "FlomoMuteDeck", "cover": "FlomoMute-Cover" },
+      "variants": [
+        { "id": "muji", "label": "原木绿", "accent": "#4ea870" },
+        { "id": "graphite", "label": "石墨灰", "accent": "#6b7785" },
+        { "id": "linen", "label": "亚麻米", "accent": "#c08a3a" }
+      ]
+    },
+    {
+      "id": "substack-drop",
+      "label": "专栏",
+      "blurb": "米色衬线 · 首字下沉 · 章节分隔 · 阅读时间 chip",
+      "accent": "#ff6719",
+      "platforms": ["公众号", "知乎", "少数派"],
+      "remotion": { "deck": "SubstackDropDeck", "cover": "SubstackDrop-Cover" },
+      "variants": [
+        { "id": "signal", "label": "信号橙", "accent": "#ff6719" },
+        { "id": "eclipse", "label": "深红夜", "accent": "#8a1f2c" },
+        { "id": "tidewater", "label": "潮汐青", "accent": "#0a5d5f" }
+      ]
+    },
+    {
+      "id": "ink-scroll",
+      "label": "卷轴",
+      "blurb": "米黄宣纸 · 楷体竖排 · 印章红 · 水墨边缘",
+      "accent": "#c0392b",
+      "platforms": ["小红书", "微博", "B 站国创区"],
+      "remotion": { "deck": "InkScrollDeck", "cover": "InkScroll-Cover" },
+      "variants": [
+        { "id": "seal-red", "label": "朱印红", "accent": "#c0392b" },
+        { "id": "seal-blue", "label": "青衣靛", "accent": "#1f3a6b" },
+        { "id": "seal-jade", "label": "翡翠绿", "accent": "#2a6b4a" }
+      ]
+    },
+    {
+      "id": "podcast-clip",
+      "label": "播客剪辑",
+      "blurb": "封面渐变 + 圆形封面 + 大字幕 · 波形 / 时间码底栏",
+      "accent": "#ffba78",
+      "platforms": ["小宇宙", "即刻", "抖音"],
+      "remotion": { "deck": "PodcastClipDeck", "cover": "PodcastClip-Cover" }
+    },
+    {
+      "id": "ink-wash",
+      "label": "新中式",
+      "blurb": "宣纸 + 思源宋体 · 横排单字 · 笔触 · 朱印 · 留白",
+      "accent": "#b3261d",
+      "platforms": ["知乎长文", "小红书", "公众号"],
+      "remotion": { "deck": "InkWashDeck", "cover": "InkWash-Cover" },
+      "variants": [
+        { "id": "vermilion", "label": "朱印红", "accent": "#b3261d" },
+        { "id": "azure", "label": "青花蓝", "accent": "#1d4a7a" },
+        { "id": "bronze", "label": "古铜褐", "accent": "#8a5a26" }
+      ]
+    },
+    {
+      "id": "morandi-calm",
+      "label": "莫兰迪",
+      "blurb": "低饱和粉褐 + 苹方 Light · 色块分区 · 零阴影零渐变",
+      "accent": "#9c5a4a",
+      "platforms": ["小红书", "公众号", "即刻"],
+      "remotion": { "deck": "MorandiCalmDeck", "cover": "MorandiCalm-Cover" }
+    },
+    {
+      "id": "douyin-data",
+      "label": "数据卡",
+      "blurb": "纯黑底 + 抖音品红 + 湖蓝 · RGB 色差 · 大数字 60%",
+      "accent": "#FE2C55",
+      "platforms": ["抖音", "视频号", "小红书"],
+      "remotion": { "deck": "DouyinDataDeck", "cover": "DouyinData-Cover" }
+    },
+    {
+      "id": "highlighter-note",
+      "label": "学习笔记",
+      "blurb": "奶油格纸 + 印刷体黑字 + Caveat 手写 · 黄色荧光笔 + 红色批注",
+      "accent": "#FFE63B",
+      "platforms": ["小红书", "B 站", "知乎"],
+      "remotion": { "deck": "HighlighterNoteDeck", "cover": "HighlighterNote-Cover" },
+      "variants": [
+        { "id": "yellow", "label": "经典荧光黄", "accent": "#FFE63B" },
+        { "id": "pink", "label": "粉色荧光", "accent": "#ff6ba0" },
+        { "id": "mint", "label": "薄荷蓝笔", "accent": "#5fc88a" }
+      ]
+    },
+    {
+      "id": "memphis-design",
+      "label": "Memphis 设计",
+      "blurb": "奶油 + 原色块 · 波浪线 + 锯齿 + 实心圆 · 1986 后现代",
+      "accent": "#ff4d6d",
+      "platforms": ["即刻", "小红书", "播客"],
+      "remotion": { "deck": "MemphisDesignDeck", "cover": "MemphisDesign-Cover" }
+    },
+    {
+      "id": "bauhaus-grid",
+      "label": "Bauhaus 包豪斯",
+      "blurb": "奶油纸 + 红黄蓝原色 + 圆方三角 · 1923 包豪斯几何构图",
+      "accent": "#d62828",
+      "platforms": ["LinkedIn", "设计博客", "工业设计", "知乎"],
+      "remotion": { "deck": "BauhausGridDeck", "cover": "BauhausGrid-Cover" }
+    },
+    {
+      "id": "riso-print",
+      "label": "双色印刷",
+      "blurb": "荧光粉 + 钴蓝错版 · 网点 + 噪点 · Risograph 独立印刷",
+      "accent": "#ff48a7",
+      "platforms": ["独立开发", "设计 newsletter", "音乐厂牌"],
+      "remotion": { "deck": "RisoPrintDeck", "cover": "RisoPrint-Cover" }
+    },
+    {
+      "id": "chrome-y2k",
+      "label": "千禧液态金属",
+      "blurb": "镀铬全息 + 像素栅 + 双径向辉光 · Y2K Bratz/iPod 质感",
+      "accent": "#8e6dff",
+      "platforms": ["小红书 girlie", "抖音 Z 世代", "TikTok"],
+      "remotion": { "deck": "ChromeY2kDeck", "cover": "ChromeY2k-Cover" }
+    },
+    {
+      "id": "botanical-press",
+      "label": "植物图谱",
+      "blurb": "羊皮纸 + Cormorant 斜体 + 拉丁学名 · 18 世纪植物标本页",
+      "accent": "#5a6d2c",
+      "platforms": ["茶道", "园艺", "慢生活"],
+      "remotion": { "deck": "BotanicalPressDeck", "cover": "BotanicalPress-Cover" },
+      "variants": [
+        { "id": "sage", "label": "鼠尾草绿", "accent": "#5a6d2c" },
+        { "id": "copper", "label": "铜版褐", "accent": "#a06340" },
+        { "id": "indigo", "label": "古典靛蓝", "accent": "#2c5078" }
+      ]
+    },
+    {
+      "id": "art-nouveau",
+      "label": "新艺术",
+      "blurb": "Mucha 曲线 + 烫金 + 装饰边框 · 1900 巴黎沙龙海报",
+      "accent": "#b07d2d",
+      "platforms": ["艺术评论", "美术志", "插画家"],
+      "remotion": { "deck": "ArtNouveauDeck", "cover": "ArtNouveau-Cover" }
+    },
+    {
+      "id": "tabloid-print",
+      "label": "小报头条",
+      "blurb": "红色 BREAKING + Anton 巨字 + 半调 + 双栏 · 八卦小报封面",
+      "accent": "#d6261a",
+      "platforms": ["行业八卦", "争议事件", "独立专栏"],
+      "remotion": { "deck": "TabloidPrintDeck", "cover": "TabloidPrint-Cover" }
+    },
+    {
+      "id": "arcade-pixel",
+      "label": "街机像素",
+      "blurb": "CRT 扫描线 + 8-bit 像素 + RGB 色差 · 80s 街机标题屏",
+      "accent": "#c5f54c",
+      "platforms": ["独立游戏", "像素艺术", "90s 复古"],
+      "remotion": { "deck": "ArcadePixelDeck", "cover": "ArcadePixel-Cover" }
+    },
+    {
+      "id": "hand-lettered",
+      "label": "黑板手写",
+      "blurb": "黑板绿底 + 粉笔白字 + Caveat 手写 · 咖啡馆菜单板",
+      "accent": "#f7d34a",
+      "platforms": ["咖啡馆菜单", "教师 notebook", "生活感"],
+      "remotion": { "deck": "HandLetteredDeck", "cover": "HandLettered-Cover" },
+      "variants": [
+        { "id": "chalkboard", "label": "黑板绿", "accent": "#f7d34a" },
+        { "id": "slate", "label": "石板灰", "accent": "#f0c84a" },
+        { "id": "kraft", "label": "牛皮纸棕", "accent": "#f5c060" }
+      ]
+    },
+    {
+      "id": "stamp-collector",
+      "label": "邮票集",
+      "blurb": "齿孔 + 邮戳 + 面额 · 复古集邮册标本页",
+      "accent": "#1f4e6b",
+      "platforms": ["旅行游记", "收藏品", "怀旧专栏"],
+      "remotion": { "deck": "StampCollectorDeck", "cover": "StampCollector-Cover" },
+      "variants": [
+        { "id": "navy", "label": "邮政蓝", "accent": "#1f4e6b" },
+        { "id": "sepia", "label": "棕褐版", "accent": "#7a4a26" },
+        { "id": "forest", "label": "森林绿", "accent": "#2a5a40" }
+      ]
+    },
+    {
+      "id": "tropical-postcard",
+      "label": "热带明信片",
+      "blurb": "落日渐变 + 椰影 + 浪潮线 · 60s 旅游海报明信片",
+      "accent": "#f04e9a",
+      "platforms": ["旅行游记", "夏日散文", "小红书 vlog"],
+      "remotion": { "deck": "TropicalPostcardDeck", "cover": "TropicalPostcard-Cover" }
+    }
+  ]
+}

package/lib/stage-core/cloud-render.js

@@ -0,0 +1,170 @@
+'use strict';
+
+/**
+ * Stage → backend bridge for the cloud Slice renderer.
+ *
+ * Background: stage runs on localhost with no auth. The backend cloud-render
+ * endpoint (`POST /api/paper-slide/render`) requires a JWT and costs 500
+ * quota per call. To let users go from "deck I'm happy with" → "mp4 in my
+ * hands" without leaving stage, we proxy three calls through the local stage
+ * server:
+ *
+ *   submit(deck)     → POST /api/paper-slide/render   { jobId }
+ *   status(jobId)    → GET  /api/render/:jobId        { status, video_url? }
+ *   quota()          → GET  /api/user/quota           { remaining, monthly }
+ *
+ * Auth: we read the same `~/.config/voxflow/token.json` cache the CLI uses.
+ * No interactive refresh — if the token is missing or expired, callers get a
+ * machine-readable `not_logged_in` code and the UI tells the user to run
+ * `voxflow login`. Auto-refresh would mean potentially launching a browser,
+ * which is the wrong move when the user already has stage open.
+ *
+ * Design choice — proxy everything: never expose the JWT to the page. The
+ * UI talks to localhost:5180/api/render-mp4 etc.; this module is the only
+ * thing that ever sees the access token. Same posture as the rest of the
+ * stage server (no third-party tabs can read it via the Origin allowlist).
+ */
+
+const http = require('http');
+const https = require('https');
+
+const { API_BASE } = require('../core/config');
+const { readCachedToken } = require('../core/auth');
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+function requestJson(targetUrl, opts = {}, body = null, timeoutMs = DEFAULT_TIMEOUT_MS) {
+  return new Promise((resolve, reject) => {
+    const u = new URL(targetUrl);
+    const mod = u.protocol === 'https:' ? https : http;
+    const headers = Object.assign({}, opts.headers || {});
+    let payload = null;
+    if (body !== null && body !== undefined) {
+      payload = Buffer.from(JSON.stringify(body), 'utf8');
+      headers['Content-Type'] = 'application/json';
+      headers['Content-Length'] = payload.length;
+    }
+    const req = mod.request({
+      hostname: u.hostname,
+      port: u.port || (u.protocol === 'https:' ? 443 : 80),
+      path: u.pathname + u.search,
+      method: opts.method || 'GET',
+      headers,
+    }, (res) => {
+      const chunks = [];
+      res.on('data', (c) => chunks.push(c));
+      res.on('end', () => {
+        const raw = Buffer.concat(chunks).toString('utf8');
+        let parsed = null;
+        try { parsed = JSON.parse(raw); } catch { /* keep as null on non-JSON */ }
+        resolve({ status: res.statusCode, data: parsed, raw });
+      });
+    });
+    req.on('error', reject);
+    req.setTimeout(timeoutMs, () => { req.destroy(new Error(`upstream timeout after ${timeoutMs}ms`)); });
+    if (payload) req.write(payload);
+    req.end();
+  });
+}
+
+/**
+ * @param {object} [opts]
+ * @param {string} [opts.apiBase=API_BASE]
+ * @param {() => ({access_token:string}|null)} [opts.tokenLoader]   For tests.
+ * @returns {{
+ *   submit: (deck:object) => Promise<{code:string, jobId?:string, message?:string, ...}>,
+ *   status: (jobId:string) => Promise<{code:string, status?:string, videoUrl?:string|null, ...}>,
+ *   quota:  () => Promise<{code:string, remaining?:number, monthly?:number, ...}>,
+ * }}
+ */
+function createCloudRenderClient(opts = {}) {
+  const apiBase = (opts.apiBase || API_BASE).replace(/\/$/, '');
+  const tokenLoader = typeof opts.tokenLoader === 'function' ? opts.tokenLoader : readCachedToken;
+
+  function authHeaders() {
+    const cached = tokenLoader();
+    if (!cached || !cached.access_token) return null;
+    return { Authorization: 'Bearer ' + cached.access_token };
+  }
+
+  async function submit(deck) {
+    if (!deck || !Array.isArray(deck.cards)) {
+      return { code: 'invalid_deck', message: 'deck.cards must be an array' };
+    }
+    const headers = authHeaders();
+    if (!headers) return { code: 'not_logged_in', message: 'Run `voxflow login` first.' };
+    let r;
+    try {
+      r = await requestJson(`${apiBase}/api/paper-slide/render`, { method: 'POST', headers }, { deck });
+    } catch (err) {
+      return { code: 'network_error', message: err.message || String(err) };
+    }
+    if (r.status === 401) return { code: 'not_logged_in', message: 'Token expired — run `voxflow login`.' };
+    if (r.status === 402 || r.status === 429) {
+      return { code: 'quota_exceeded', message: r.data?.message || 'Insufficient quota' };
+    }
+    if (r.status >= 400 || !r.data) {
+      return { code: r.data?.code || 'render_submit_failed', message: r.data?.message || `HTTP ${r.status}` };
+    }
+    const jobId = r.data.data?.jobId || r.data.jobId;
+    if (!jobId) return { code: 'render_submit_failed', message: 'no jobId in response' };
+    return { code: 'success', jobId };
+  }
+
+  async function status(jobId) {
+    if (typeof jobId !== 'string' || jobId.length === 0) {
+      return { code: 'invalid_id', message: 'jobId required' };
+    }
+    const headers = authHeaders();
+    if (!headers) return { code: 'not_logged_in', message: 'Run `voxflow login` first.' };
+    let r;
+    try {
+      r = await requestJson(`${apiBase}/api/render/${encodeURIComponent(jobId)}`, { method: 'GET', headers });
+    } catch (err) {
+      return { code: 'network_error', message: err.message || String(err) };
+    }
+    if (r.status === 401) return { code: 'not_logged_in' };
+    if (r.status === 404) return { code: 'job_not_found' };
+    if (r.status >= 400 || !r.data) {
+      return { code: r.data?.code || 'status_failed', message: r.data?.message || `HTTP ${r.status}` };
+    }
+    const job = r.data.data || r.data;
+    return {
+      code: 'success',
+      status: job.status,
+      videoUrl: job.video_url || job.videoUrl || null,
+      progress: job.progress,
+    };
+  }
+
+  async function quota() {
+    const headers = authHeaders();
+    if (!headers) return { code: 'not_logged_in' };
+    let r;
+    try {
+      r = await requestJson(`${apiBase}/api/user/quota`, { method: 'GET', headers });
+    } catch (err) {
+      return { code: 'network_error', message: err.message };
+    }
+    if (r.status === 401) return { code: 'not_logged_in' };
+    if (r.status >= 400 || !r.data) {
+      return { code: 'quota_lookup_failed', message: `HTTP ${r.status}` };
+    }
+    const q = r.data.data || r.data;
+    return {
+      code: 'success',
+      remaining: typeof q.remaining === 'number' ? q.remaining : null,
+      monthly: typeof q.monthly === 'number' ? q.monthly : null,
+      bonus: typeof q.bonus === 'number' ? q.bonus : null,
+    };
+  }
+
+  return { submit, status, quota };
+}
+
+// The render quota cost is hardcoded backend-side (500 per cloud-render).
+// We expose it here so the UI can show "this costs N quota" without an
+// extra round-trip — keep this in sync if the backend ladder changes.
+const CLOUD_RENDER_COST = 500;
+
+module.exports = { createCloudRenderClient, CLOUD_RENDER_COST };

package/lib/stage-core/deck-format.js

@@ -0,0 +1,133 @@
+'use strict';
+
+/**
+ * Pure deck formatters used by the Stage UI (browser-side via stringification)
+ * AND by node:test units. Keep self-contained — no closures, no requires —
+ * because `Function.prototype.toString()` ships the source verbatim into the
+ * UI HTML and the browser then `eval`s the body inside an IIFE.
+ *
+ * Inputs are deliberately defensive about unknown card shapes (slice deck
+ * cards have varied kinds: title / body / outro; not every card has every
+ * field). Outputs are plain strings — clipboard-ready, no HTML escaping
+ * (browsers handle that on paste).
+ */
+
+/**
+ * Convert a single Slice card to a plain-text snippet — the kind a user
+ * would paste into X / Twitter / 即刻 / 公众号 caption / 微博:
+ *
+ *   {title}
+ *   {caption (if distinct from title)}
+ *
+ *   {narration}
+ *
+ * Empty fields are skipped. Returns '' if the card has nothing useful.
+ *
+ * @param {object} card    Slice deck card (any shape)
+ * @returns {string}
+ */
+function formatCardAsText(card) {
+  if (!card || typeof card !== 'object') return '';
+  const lines = [];
+  let title = null;
+  if (Array.isArray(card.title)) title = card.title.join(' · ');
+  else if (typeof card.title === 'string') title = card.title;
+  if (title && title.trim()) lines.push(title.trim());
+
+  if (typeof card.caption === 'string'
+      && card.caption.trim()
+      && card.caption.trim() !== title) {
+    lines.push(card.caption.trim());
+  }
+
+  if (typeof card.narration === 'string' && card.narration.trim()) {
+    if (lines.length > 0) lines.push('');
+    lines.push(card.narration.trim());
+  }
+
+  return lines.join('\n').trim();
+}
+
+/**
+ * Convert a whole Slice deck to a clean Markdown document. Useful for pasting
+ * into Notion / blog editors / 飞书 docs / hand-formatting elsewhere:
+ *
+ *   # {seriesTitle || header || 'Deck'}
+ *
+ *   ## 1. {card title}
+ *
+ *   {caption if distinct}
+ *
+ *   > {narration, multi-line preserved as blockquote}
+ *
+ * Returns '' if the deck shape is unusable.
+ *
+ * @param {object} deck
+ * @returns {string}
+ */
+function formatDeckAsMarkdown(deck) {
+  if (!deck || typeof deck !== 'object') return '';
+  const out = [];
+  const top = (typeof deck.seriesTitle === 'string' && deck.seriesTitle.trim())
+    || (typeof deck.header === 'string' && deck.header.trim())
+    || 'Deck';
+  out.push('# ' + top);
+  out.push('');
+
+  const cards = Array.isArray(deck.cards) ? deck.cards : [];
+  for (let i = 0; i < cards.length; i++) {
+    const c = cards[i] || {};
+    let title = null;
+    if (Array.isArray(c.title)) title = c.title.join(' · ');
+    else if (typeof c.title === 'string') title = c.title;
+    if (!title || !title.trim()) {
+      title = (typeof c.caption === 'string' && c.caption.trim())
+        ? c.caption.trim()
+        : 'Card ' + (i + 1);
+    }
+    out.push('## ' + (i + 1) + '. ' + title);
+    out.push('');
+
+    if (typeof c.caption === 'string'
+        && c.caption.trim()
+        && c.caption.trim() !== title) {
+      out.push(c.caption.trim());
+      out.push('');
+    }
+
+    if (typeof c.narration === 'string' && c.narration.trim()) {
+      // Multi-line narration → each line gets the blockquote prefix.
+      const quoted = c.narration.trim().split('\n').map((ln) => '> ' + ln).join('\n');
+      out.push(quoted);
+      out.push('');
+    }
+  }
+
+  return out.join('\n').trim() + '\n';
+}
+
+/**
+ * Suggest a friendly filename for the deck JSON download. Sanitises the
+ * deck title to filesystem-safe ASCII and tacks on `.json`.
+ *
+ * @param {object} deck
+ * @returns {string}
+ */
+function suggestDeckFilename(deck) {
+  const top = (deck && typeof deck.seriesTitle === 'string' && deck.seriesTitle.trim())
+    || (deck && typeof deck.header === 'string' && deck.header.trim())
+    || 'deck';
+  const safe = top
+    .replace(/[<>:"/\\|?*]+/g, '-')
+    .replace(/\s+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 60);
+  return (safe || 'deck') + '.json';
+}
+
+module.exports = {
+  formatCardAsText,
+  formatDeckAsMarkdown,
+  suggestDeckFilename,
+};