create-promptframe-component 0.0.0 → 0.1.0

package/README.md

@@ -1,6 +1,5 @@
 # create-promptframe-component
 
-Project scaffolder for PromptFrame-compatible components.
-
-This `0.0.0` release is a placeholder that reserves the package name and trusted publishing route. The first functional release will start at `0.1.0`.
+Create a PromptFrame-compatible Remotion component project from the standard React template.
 
+The generated project has no Git remote by default. It is meant to be validated and uploaded through `@promptframe/cli`.

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 #!/usr/bin/env node
+export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,4 +1,68 @@
 #!/usr/bin/env node
-"use strict";
-console.log('create-promptframe-component 0.0.0 placeholder. Functional scaffolding will ship in 0.1.0.');
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const targetArg = process.argv[2];
+if (!targetArg || targetArg === '--help' || targetArg === '-h') {
+    console.log('Usage: npm create promptframe-component <component-dir> [--display-name "Sales Funnel"]');
+    process.exit(targetArg ? 0 : 1);
+}
+const targetDir = resolve(targetArg);
+if (existsSync(targetDir) && readdirSync(targetDir).length > 0) {
+    console.error(`create.target_not_empty: ${targetDir} is not empty`);
+    process.exit(1);
+}
+const componentName = toKebabName(targetArg.split(/[\\/]/).filter(Boolean).at(-1) ?? 'promptframe-component');
+const displayName = valueAfter(process.argv.slice(3), '--display-name') ?? toTitle(componentName);
+const description = valueAfter(process.argv.slice(3), '--description') ?? `${displayName} PromptFrame component`;
+const packageRoot = dirname(fileURLToPath(import.meta.url));
+const templateDir = resolve(packageRoot, '../templates/react-remotion');
+copyTemplate(templateDir, targetDir, {
+    __COMPONENT_NAME__: componentName,
+    __DISPLAY_NAME__: displayName,
+    __DESCRIPTION__: description,
+});
+console.log(`Created PromptFrame component at ${targetDir}`);
+console.log('Next steps: npm install && npm run validate');
+function copyTemplate(from, to, replacements) {
+    mkdirSync(to, { recursive: true });
+    for (const entry of readdirSync(from)) {
+        const src = join(from, entry);
+        const dest = join(to, entry);
+        const stat = statSync(src);
+        if (stat.isDirectory()) {
+            copyTemplate(src, dest, replacements);
+            continue;
+        }
+        if (isTextFile(src)) {
+            let text = readFileSync(src, 'utf8');
+            for (const [key, value] of Object.entries(replacements))
+                text = text.replaceAll(key, value);
+            writeFileSync(dest, text);
+        }
+        else {
+            copyFileSync(src, dest);
+        }
+    }
+}
+function isTextFile(path) {
+    return /\.(json|md|js|ts|tsx|yml|yaml|css|html)$/.test(path);
+}
+function valueAfter(argv, flag) {
+    const index = argv.indexOf(flag);
+    if (index < 0)
+        return undefined;
+    return argv[index + 1];
+}
+function toKebabName(value) {
+    return value
+        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 63) || 'promptframe-component';
+}
+function toTitle(value) {
+    return value.split('-').filter(Boolean).map((part) => part[0]?.toUpperCase() + part.slice(1)).join(' ');
+}
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;AAEA,OAAO,CAAC,GAAG,CAAC,4FAA4F,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAClH,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClC,IAAI,CAAC,SAAS,IAAI,SAAS,KAAK,QAAQ,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;IAC/D,OAAO,CAAC,GAAG,CAAC,yFAAyF,CAAC,CAAC;IACvG,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAClC,CAAC;AAED,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;AACrC,IAAI,UAAU,CAAC,SAAS,CAAC,IAAI,WAAW,CAAC,SAAS,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;IAC/D,OAAO,CAAC,KAAK,CAAC,4BAA4B,SAAS,eAAe,CAAC,CAAC;IACpE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,MAAM,aAAa,GAAG,WAAW,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,uBAAuB,CAAC,CAAC;AAC9G,MAAM,WAAW,GAAG,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,gBAAgB,CAAC,IAAI,OAAO,CAAC,aAAa,CAAC,CAAC;AAClG,MAAM,WAAW,GAAG,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,eAAe,CAAC,IAAI,GAAG,WAAW,wBAAwB,CAAC;AACjH,MAAM,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC5D,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,EAAE,6BAA6B,CAAC,CAAC;AAExE,YAAY,CAAC,WAAW,EAAE,SAAS,EAAE;IACnC,kBAAkB,EAAE,aAAa;IACjC,gBAAgB,EAAE,WAAW;IAC7B,eAAe,EAAE,WAAW;CAC7B,CAAC,CAAC;AAEH,OAAO,CAAC,GAAG,CAAC,oCAAoC,SAAS,EAAE,CAAC,CAAC;AAC7D,OAAO,CAAC,GAAG,CAAC,6CAA6C,CAAC,CAAC;AAE3D,SAAS,YAAY,CAAC,IAAY,EAAE,EAAU,EAAE,YAAoC;IAClF,SAAS,CAAC,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACnC,KAAK,MAAM,KAAK,IAAI,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC;QACtC,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAC9B,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;QAC7B,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;QAC3B,IAAI,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;YACvB,YAAY,CAAC,GAAG,EAAE,IAAI,EAAE,YAAY,CAAC,CAAC;YACtC,SAAS;QACX,CAAC;QACD,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACpB,IAAI,IAAI,GAAG,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;YACrC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC;gBAAE,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YAC5F,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC5B,CAAC;aAAM,CAAC;YACN,YAAY,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC;AACH,CAAC;AAED,SAAS,UAAU,CAAC,IAAY;IAC9B,OAAO,0CAA0C,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC/D,CAAC;AAED,SAAS,UAAU,CAAC,IAAc,EAAE,IAAY;IAC9C,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,IAAI,KAAK,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAChC,OAAO,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;AACzB,CAAC;AAED,SAAS,WAAW,CAAC,KAAa;IAChC,OAAO,KAAK;SACT,OAAO,CAAC,oBAAoB,EAAE,OAAO,CAAC;SACtC,WAAW,EAAE;SACb,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC;SAC3B,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC;SACvB,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,uBAAuB,CAAC;AAC7C,CAAC;AAED,SAAS,OAAO,CAAC,KAAa;IAC5B,OAAO,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC1G,CAAC"}

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "create-promptframe-component",
-  "version": "0.0.0",
+  "version": "0.1.0",
   "license": "MIT",
   "type": "module",
   "files": [
     "dist",
+    "templates",
     "README.md"
   ],
   "bin": {
@@ -41,8 +42,8 @@
     "test": "node -e \"console.log('placeholder test: create-promptframe-component')\"",
     "clean": "rm -rf dist"
   },
-  "dependencies": {},
   "devDependencies": {
+    "@types/node": "^24.12.4",
     "typescript": "~5.7.0"
   }
 }

package/templates/react-remotion/README.md

@@ -0,0 +1,88 @@
+# __DISPLAY_NAME__
+
+平台标准 Remotion 组件市场组件。
+
+## 本地开发
+
+```bash
+npm install
+npm run validate
+```
+
+如果你是冷启动 AI，先不要发散改目录结构。请按下面顺序做：
+
+```bash
+npx promptframe standard
+npx promptframe doctor .
+npx promptframe validate .
+npx promptframe upload . --endpoint <promptframe-api-base>
+npx promptframe status <jobId> --endpoint <promptframe-api-base>
+```
+
+如果上传入口不可用，仍然要完成本地开发和 `validate`，然后按组件作者报告模板写清本地结果。
+
+## 必需文件
+
+- `src/Component.tsx`：确定性的 Remotion 组件。
+- `src/schema.ts`：Zod props schema（参数 schema）和默认 props。
+- `src/preview-props.json`：有边界的默认预览参数。
+- `manifest.json`：组件身份、版本、分类、审核状态和 hash 信息。
+
+## 时间轴规则
+
+- 所有动画必须由 `useCurrentFrame()` / `useVideoConfig()` 驱动。
+- `manifest.json` 的 `designedDurationRange` 表示舒服播放区间，不是硬编码场景时长。
+- 组件要能适配不同 `durationFrames`：时间不足时加速关键动作，时间富裕时保持最终态。
+- 禁止 CSS `transition`、`@keyframes`、计时器、`Date.now()`、`Math.random()`。
+
+项目级规则见 PromptFrame authoring skill 的 `rules/timing-ssot.md`。
+
+## 检索元数据
+
+组件作者可以维护标题、摘要、描述、标签和参数说明。平台会根据源码、schema、依赖、预览画面和渲染结果生成不可手改的证据层，用于防止描述和真实能力不一致。
+
+如果描述写得夸张但源码/预览证据不支持，组件不会一定被拦截，但会收到提示并影响公开市场排序。
+
+动态数据组件可以参考 PromptFrame authoring skill 的 `rules/schema-recipes.md`，里面有增长指标、对比指标、漏斗阶段和正负 delta 的推荐 schema 写法。
+
+本地校验通过后，使用 `@promptframe/cli` 上传。
+
+## 安全策略
+
+安全规则来自平台标准 API。CLI 本地 `promptframe validate .` 和服务端准入会使用同一套公开 ruleId 口径，并在报错中显示 `ruleId`。
+
+- 不要使用 `eval`、`new Function`、字符串定时器、`node:fs`、`child_process`、`process.env`。
+- 不要直接使用 `fetch()` / XHR / WebSocket / Beacon。
+- 即使使用 `componentRuntime.fetchJson()`，也必须等待平台提供白名单配置；未配置时会进入 `manual_review`。
+- 不要读取 `localStorage` / `sessionStorage` / cookie。当前可能只是 warning，但不建议保留。
+- 需要素材、状态或外部数据时，让平台通过 props / asset / 后续受控 wrapper 注入。
+
+## 上传与状态
+
+推荐直接上传组件目录：
+
+```bash
+npx promptframe upload . --endpoint <promptframe-api-base>
+```
+
+`upload .` 是推荐的一步式入口，会自动完成 validate、package 和上传。`package` 只用于离线传输或排查 zip 内容。
+
+如果平台入口不可用，先保留本地校验结果和错误输出，不要把服务地址写进源码、manifest 或组件 README。
+
+查看构建验收状态：
+
+```bash
+npx promptframe status <jobId> --endpoint <promptframe-api-base>
+```
+
+上传成功只代表服务端已接收源码并执行构建验收，不等于组件已经公开发布。
+
+如果平台提示预览资产是平台环境问题，平台维护者修复后可重新生成预览：
+
+```bash
+npx promptframe reindex <jobId> --endpoint <promptframe-api-base>
+```
+
+## 组件包边界
+
+本组件目录是上传、构建和验收边界。源码文件可以引用组件目录内部文件，但不能引用组件目录外的本地文件，也不要依赖本地 path alias。需要复用的公共能力应来自 npm 包或平台标准包，例如 `@promptframe/component-kit`。

package/templates/react-remotion/eslint.config.js

@@ -0,0 +1,36 @@
+import js from '@eslint/js';
+import globals from 'globals';
+import reactHooks from 'eslint-plugin-react-hooks';
+import reactRefresh from 'eslint-plugin-react-refresh';
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config(
+  { ignores: ['dist'] },
+  {
+    extends: [js.configs.recommended, ...tseslint.configs.recommended],
+    files: ['**/*.{ts,tsx}'],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+    },
+    plugins: {
+      'react-hooks': reactHooks,
+      'react-refresh': reactRefresh,
+    },
+    rules: {
+      ...reactHooks.configs.recommended.rules,
+      'react-refresh/only-export-components': ['warn', { allowConstantExport: true }],
+      'no-restricted-syntax': [
+        'error',
+        {
+          selector: "CallExpression[callee.object.name='Math'][callee.property.name='random']",
+          message: 'Use remotion random(seed) instead of Math.random().',
+        },
+        {
+          selector: "CallExpression[callee.object.name='Date'][callee.property.name='now']",
+          message: 'Frame output must not depend on Date.now().',
+        },
+      ],
+    },
+  },
+);

package/templates/react-remotion/manifest.json

@@ -0,0 +1,38 @@
+{
+  "schemaVersion": "component-manifest.v0.1.0",
+  "standardVersion": "component-standard.v0.1.0",
+  "standardSourceHash": "sha256:8c1e01c36155b4b646981064d24df9bd8cda501fd9cd9da93e5b62f40db22d52",
+  "id": "@marketplace/__COMPONENT_NAME__",
+  "name": "__COMPONENT_NAME__",
+  "displayName": "__DISPLAY_NAME__",
+  "version": "0.1.0",
+  "componentType": "scene_template",
+  "trustLevel": "untrusted_temporary",
+  "author": {
+    "id": "local-user",
+    "name": "Local User"
+  },
+  "description": "__DESCRIPTION__",
+  "tags": ["custom", "marketplace", "remotion"],
+  "designedDurationRange": {
+    "min": 90,
+    "max": 180
+  },
+  "entry": {
+    "sourcePath": "src/Component.tsx",
+    "componentExport": "default",
+    "propsSchemaPath": "src/schema.ts",
+    "sourceHash": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
+    "schemaHash": "sha256:0000000000000000000000000000000000000000000000000000000000000000"
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "remotion": "^4.0.0"
+  },
+  "assets": {},
+  "capabilityHints": ["animated scene template"],
+  "reviewStatus": "draft",
+  "license": "proprietary",
+  "createdAt": "2026-05-13T00:00:00.000Z"
+}

package/templates/react-remotion/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "__COMPONENT_NAME__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite --host 127.0.0.1",
+    "build": "tsc --noEmit && vite build",
+    "lint": "eslint .",
+    "format": "prettier --check .",
+    "test": "vitest run",
+    "validate": "npm run lint && npm run test && npm run build"
+  },
+  "dependencies": {
+    "@promptframe/component-kit": "^0.1.3",
+    "@promptframe/contracts": "^0.1.0",
+    "@vitejs/plugin-react": "^6.0.1",
+    "vite": "^8.0.10",
+    "typescript": "~6.0.2",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "remotion": "^4.0.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "eslint": "^10.2.1",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "eslint-plugin-react-refresh": "^0.5.2",
+    "globals": "^17.5.0",
+    "prettier": "^3.5.0",
+    "typescript-eslint": "^8.58.2",
+    "vitest": "^3.0.0"
+  }
+}

package/templates/react-remotion/prettier.config.js

@@ -0,0 +1,5 @@
+export default {
+  singleQuote: true,
+  trailingComma: 'all',
+  printWidth: 100,
+};

package/templates/react-remotion/src/Component.test.tsx

@@ -0,0 +1,10 @@
+import { describe, expect, it } from 'vitest';
+import { defaultProps, propsSchema } from './schema';
+
+describe('__COMPONENT_NAME__ props schema', () => {
+  it('provides bounded default preview props', () => {
+    expect(propsSchema.parse(defaultProps)).toMatchObject({
+      title: '__DISPLAY_NAME__',
+    });
+  });
+});

package/templates/react-remotion/src/Component.tsx

@@ -0,0 +1,32 @@
+import { AbsoluteFill, interpolate, useCurrentFrame, useVideoConfig } from 'remotion';
+import type { ComponentProps } from './schema';
+
+export default function Component(props: ComponentProps) {
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+  const progress = interpolate(frame, [0, Math.max(1, fps * 2)], [0, 1], {
+    extrapolateLeft: 'clamp',
+    extrapolateRight: 'clamp',
+  });
+
+  return (
+    <AbsoluteFill
+      style={{
+        background: props.background,
+        color: props.foreground,
+        fontFamily: 'Inter, ui-sans-serif, system-ui, sans-serif',
+        justifyContent: 'center',
+        padding: 72,
+      }}
+    >
+      <div style={{ opacity: progress, transform: `translateY(${(1 - progress) * 24}px)` }}>
+        <p style={{ margin: 0, fontSize: 24, letterSpacing: 0, opacity: 0.72 }}>
+          {props.kicker}
+        </p>
+        <h1 style={{ margin: '12px 0 0', fontSize: 68, lineHeight: 1.02, letterSpacing: 0 }}>
+          {props.title}
+        </h1>
+      </div>
+    </AbsoluteFill>
+  );
+}

package/templates/react-remotion/src/index.ts

@@ -0,0 +1,2 @@
+export { default as Component } from './Component';
+export { defaultProps, propsSchema, type ComponentProps } from './schema';

package/templates/react-remotion/src/preview-props.json

@@ -0,0 +1,12 @@
+{
+  "durationFrames": 120,
+  "fps": 30,
+  "width": 1280,
+  "height": 720,
+  "props": {
+    "kicker": "Marketplace Component",
+    "title": "__DISPLAY_NAME__",
+    "background": "#101114",
+    "foreground": "#f4f1ea"
+  }
+}

package/templates/react-remotion/src/schema.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+
+export const propsSchema = z.object({
+  kicker: z.string().default('Marketplace Component'),
+  title: z.string().default('__DISPLAY_NAME__'),
+  background: z.string().default('#101114'),
+  foreground: z.string().default('#f4f1ea'),
+});
+
+export type ComponentProps = z.infer<typeof propsSchema>;
+
+export const defaultProps: ComponentProps = propsSchema.parse({});

package/templates/react-remotion/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "allowJs": false,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "forceConsistentCasingInFileNames": true,
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx"
+  },
+  "include": ["src"]
+}

package/templates/react-remotion/vite.config.ts

@@ -0,0 +1,16 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+  build: {
+    lib: {
+      entry: 'src/index.ts',
+      formats: ['es'],
+      fileName: () => 'index.js',
+    },
+    rollupOptions: {
+      external: ['react', 'react-dom', 'react/jsx-runtime', 'remotion'],
+    },
+  },
+});