@promptframe/component-kit 0.1.0

package/README.md

@@ -0,0 +1,35 @@
+# @promptframe/component-kit
+
+Stable helper package for Remotion marketplace component authors.
+
+This package is intentionally small. It exposes standard stamps, preview constraints, and deterministic timing helpers that external/private components can depend on without importing renderer internals.
+
+## Public Entrypoints
+
+```ts
+import { getComponentStandardStamp } from '@promptframe/component-kit';
+import { COMPONENT_PREVIEW_CONSTRAINTS } from '@promptframe/component-kit/preview';
+import { createDurationTimeline } from '@promptframe/component-kit/timing';
+```
+
+The package does not replace server-side admission. Uploads must still pass build admission, deterministic security review, manifest/schema/policy validation, evidence indexing, artifact mirror, and `get_component_schema` before Director can use the component.
+
+## Authoring Rules
+
+- Do not import `@remotion-media/renderer` or repo-internal paths from component packages.
+- Keep Remotion/React as the component project's own dependencies; `component-kit` declares them as optional peers only for future helper compatibility.
+- Treat `getComponentStandardStamp()` as a local development stamp. The platform API and server admission remain the final SSOT.
+- Use `component-market validate --online` before upload and `component-market upload` for admission.
+
+## Publishing Status
+
+The package is public-release ready. The confirmed public coordinates are:
+
+- npm package: `@promptframe/component-kit`
+- npm org/scope: `@promptframe`
+- release repository: `https://github.com/ty-teams/promptframe-component-kit`
+- license: MIT
+
+First publish still requires the npm account's OTP/2FA path and npm Trusted Publisher configuration; do not add an `NPM_TOKEN` secret.
+
+Marketplace/private components themselves do not publish to npm. They still move through platform CLI upload, build admission, security review, schema/policy/receipt generation, evidence indexing, artifact mirror, and resolver-backed preview/render.

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './preview.js';
+export * from './standard.js';
+export * from './timing.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from './preview.js';
+export * from './standard.js';
+export * from './timing.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC"}

package/dist/preview.d.ts

@@ -0,0 +1,16 @@
+export interface ComponentPreviewConstraints {
+    maxDurationFrames: number;
+    maxWidth: number;
+    maxHeight: number;
+    maxFps: number;
+}
+export declare const COMPONENT_PREVIEW_CONSTRAINTS: ComponentPreviewConstraints;
+export interface ComponentPreviewPropsEnvelope<TProps extends Record<string, unknown> = Record<string, unknown>> {
+    durationFrames: number;
+    fps: 30;
+    width: number;
+    height: number;
+    props: TProps;
+}
+export declare function assertPreviewWithinConstraints(preview: ComponentPreviewPropsEnvelope, constraints?: ComponentPreviewConstraints): void;
+//# sourceMappingURL=preview.d.ts.map

package/dist/preview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview.d.ts","sourceRoot":"","sources":["../src/preview.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,2BAA2B;IAC1C,iBAAiB,EAAE,MAAM,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,eAAO,MAAM,6BAA6B,EAAE,2BAK3C,CAAC;AAEF,MAAM,WAAW,6BAA6B,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC7G,cAAc,EAAE,MAAM,CAAC;IACvB,GAAG,EAAE,EAAE,CAAC;IACR,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,6BAA6B,EACtC,WAAW,GAAE,2BAA2D,GACvE,IAAI,CAON"}

package/dist/preview.js

@@ -0,0 +1,20 @@
+export const COMPONENT_PREVIEW_CONSTRAINTS = {
+    maxDurationFrames: 180,
+    maxWidth: 1280,
+    maxHeight: 720,
+    maxFps: 30,
+};
+export function assertPreviewWithinConstraints(preview, constraints = COMPONENT_PREVIEW_CONSTRAINTS) {
+    const errors = [];
+    if (preview.durationFrames > constraints.maxDurationFrames)
+        errors.push(`durationFrames must be <= ${constraints.maxDurationFrames}`);
+    if (preview.width > constraints.maxWidth)
+        errors.push(`width must be <= ${constraints.maxWidth}`);
+    if (preview.height > constraints.maxHeight)
+        errors.push(`height must be <= ${constraints.maxHeight}`);
+    if (preview.fps > constraints.maxFps)
+        errors.push(`fps must be <= ${constraints.maxFps}`);
+    if (errors.length > 0)
+        throw new Error(errors.join('; '));
+}
+//# sourceMappingURL=preview.js.map

package/dist/preview.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview.js","sourceRoot":"","sources":["../src/preview.ts"],"names":[],"mappings":"AAOA,MAAM,CAAC,MAAM,6BAA6B,GAAgC;IACxE,iBAAiB,EAAE,GAAG;IACtB,QAAQ,EAAE,IAAI;IACd,SAAS,EAAE,GAAG;IACd,MAAM,EAAE,EAAE;CACX,CAAC;AAUF,MAAM,UAAU,8BAA8B,CAC5C,OAAsC,EACtC,cAA2C,6BAA6B;IAExE,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,OAAO,CAAC,cAAc,GAAG,WAAW,CAAC,iBAAiB;QAAE,MAAM,CAAC,IAAI,CAAC,6BAA6B,WAAW,CAAC,iBAAiB,EAAE,CAAC,CAAC;IACtI,IAAI,OAAO,CAAC,KAAK,GAAG,WAAW,CAAC,QAAQ;QAAE,MAAM,CAAC,IAAI,CAAC,oBAAoB,WAAW,CAAC,QAAQ,EAAE,CAAC,CAAC;IAClG,IAAI,OAAO,CAAC,MAAM,GAAG,WAAW,CAAC,SAAS;QAAE,MAAM,CAAC,IAAI,CAAC,qBAAqB,WAAW,CAAC,SAAS,EAAE,CAAC,CAAC;IACtG,IAAI,OAAO,CAAC,GAAG,GAAG,WAAW,CAAC,MAAM;QAAE,MAAM,CAAC,IAAI,CAAC,kBAAkB,WAAW,CAAC,MAAM,EAAE,CAAC,CAAC;IAC1F,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;AAC5D,CAAC"}

package/dist/standard.d.ts

@@ -0,0 +1,15 @@
+export declare const COMPONENT_STANDARD_VERSION: "component-standard.v0.1.0";
+export declare const COMPONENT_STANDARD_SOURCE_HASH: "sha256:8c1e01c36155b4b646981064d24df9bd8cda501fd9cd9da93e5b62f40db22d52";
+export declare const COMPONENT_STANDARD_SOURCE_PATH: "docs/requirements/REQ-073/component-standard.md";
+export declare const COMPONENT_KIT_VERSION: "0.1.0";
+export declare const COMPONENT_MANIFEST_SCHEMA_VERSION: "component-manifest.v0.1.0";
+export declare const COMPONENT_REVIEW_CHECKLIST_VERSION: "component-review-checklist.v0.1.0";
+export declare function getComponentStandardStamp(): {
+    sourceVersion: "component-standard.v0.1.0";
+    sourceHash: "sha256:8c1e01c36155b4b646981064d24df9bd8cda501fd9cd9da93e5b62f40db22d52";
+    sourcePath: "docs/requirements/REQ-073/component-standard.md";
+    componentKitVersion: "0.1.0";
+    manifestSchemaVersion: "component-manifest.v0.1.0";
+    reviewChecklistVersion: "component-review-checklist.v0.1.0";
+};
+//# sourceMappingURL=standard.d.ts.map

package/dist/standard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"standard.d.ts","sourceRoot":"","sources":["../src/standard.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,0BAA0B,EAAG,2BAAoC,CAAC;AAC/E,eAAO,MAAM,8BAA8B,EAAG,yEAAkF,CAAC;AACjI,eAAO,MAAM,8BAA8B,EAAG,iDAA0D,CAAC;AACzG,eAAO,MAAM,qBAAqB,EAAG,OAAgB,CAAC;AACtD,eAAO,MAAM,iCAAiC,EAAG,2BAAoC,CAAC;AACtF,eAAO,MAAM,kCAAkC,EAAG,mCAA4C,CAAC;AAE/F,wBAAgB,yBAAyB;;;;;;;EASxC"}

package/dist/standard.js

@@ -0,0 +1,17 @@
+export const COMPONENT_STANDARD_VERSION = 'component-standard.v0.1.0';
+export const COMPONENT_STANDARD_SOURCE_HASH = 'sha256:8c1e01c36155b4b646981064d24df9bd8cda501fd9cd9da93e5b62f40db22d52';
+export const COMPONENT_STANDARD_SOURCE_PATH = 'docs/requirements/REQ-073/component-standard.md';
+export const COMPONENT_KIT_VERSION = '0.1.0';
+export const COMPONENT_MANIFEST_SCHEMA_VERSION = 'component-manifest.v0.1.0';
+export const COMPONENT_REVIEW_CHECKLIST_VERSION = 'component-review-checklist.v0.1.0';
+export function getComponentStandardStamp() {
+    return {
+        sourceVersion: COMPONENT_STANDARD_VERSION,
+        sourceHash: COMPONENT_STANDARD_SOURCE_HASH,
+        sourcePath: COMPONENT_STANDARD_SOURCE_PATH,
+        componentKitVersion: COMPONENT_KIT_VERSION,
+        manifestSchemaVersion: COMPONENT_MANIFEST_SCHEMA_VERSION,
+        reviewChecklistVersion: COMPONENT_REVIEW_CHECKLIST_VERSION,
+    };
+}
+//# sourceMappingURL=standard.js.map

package/dist/standard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"standard.js","sourceRoot":"","sources":["../src/standard.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,0BAA0B,GAAG,2BAAoC,CAAC;AAC/E,MAAM,CAAC,MAAM,8BAA8B,GAAG,yEAAkF,CAAC;AACjI,MAAM,CAAC,MAAM,8BAA8B,GAAG,iDAA0D,CAAC;AACzG,MAAM,CAAC,MAAM,qBAAqB,GAAG,OAAgB,CAAC;AACtD,MAAM,CAAC,MAAM,iCAAiC,GAAG,2BAAoC,CAAC;AACtF,MAAM,CAAC,MAAM,kCAAkC,GAAG,mCAA4C,CAAC;AAE/F,MAAM,UAAU,yBAAyB;IACvC,OAAO;QACL,aAAa,EAAE,0BAA0B;QACzC,UAAU,EAAE,8BAA8B;QAC1C,UAAU,EAAE,8BAA8B;QAC1C,mBAAmB,EAAE,qBAAqB;QAC1C,qBAAqB,EAAE,iCAAiC;QACxD,sBAAsB,EAAE,kCAAkC;KAC3D,CAAC;AACJ,CAAC"}

package/dist/timing.d.ts

@@ -0,0 +1,24 @@
+export interface DurationTimeline {
+    actualDuration: number;
+    designedDuration: number;
+    actionDuration: number;
+    scale: number;
+    holdFrames: number;
+    at(frame: number): number;
+    frame(value: number): number;
+    range(start: number, end: number): [number, number];
+    stagger(baseDelay: number, index: number, baseStagger: number): number;
+    scaledFps(actualFps: number): number;
+}
+export interface CreateDurationTimelineParams {
+    actualDuration: number;
+    designedDuration: number;
+    minScale?: number;
+}
+export declare function createDurationTimeline(params: CreateDurationTimelineParams): DurationTimeline;
+export interface ScaledSpringTiming {
+    frame: number;
+    fps: number;
+}
+export declare function getScaledSpringTiming(frame: number, fps: number, delay: number, timeline: DurationTimeline): ScaledSpringTiming;
+//# sourceMappingURL=timing.d.ts.map

package/dist/timing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timing.d.ts","sourceRoot":"","sources":["../src/timing.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,gBAAgB;IAC/B,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1B,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAC7B,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpD,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAAC;IACvE,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;CACtC;AAED,MAAM,WAAW,4BAA4B;IAC3C,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,4BAA4B,GAAG,gBAAgB,CA2B7F;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACb;AAED,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,gBAAgB,GACzB,kBAAkB,CAKpB"}

package/dist/timing.js

@@ -0,0 +1,39 @@
+export function createDurationTimeline(params) {
+    const actualDuration = positiveInteger(params.actualDuration, 'actualDuration');
+    const designedDuration = positiveInteger(params.designedDuration, 'designedDuration');
+    const minScale = params.minScale ?? 0.3;
+    if (minScale <= 0 || minScale > 1)
+        throw new Error('minScale must be > 0 and <= 1');
+    const rawScale = Math.min(actualDuration, designedDuration) / designedDuration;
+    const scale = Math.max(minScale, rawScale);
+    const actionDuration = Math.round(designedDuration * scale);
+    const holdFrames = Math.max(0, actualDuration - actionDuration);
+    const at = (frame) => Math.round(frame * scale);
+    const range = (start, end) => [at(start), at(end)];
+    const stagger = (baseDelay, index, baseStagger) => at(baseDelay + index * baseStagger);
+    const scaledFps = (actualFps) => scale < 1 ? actualFps / scale : actualFps;
+    return {
+        actualDuration,
+        designedDuration,
+        actionDuration,
+        scale,
+        holdFrames,
+        at,
+        frame: at,
+        range,
+        stagger,
+        scaledFps,
+    };
+}
+export function getScaledSpringTiming(frame, fps, delay, timeline) {
+    return {
+        frame: Math.max(0, frame - timeline.at(delay)),
+        fps: timeline.scaledFps(fps),
+    };
+}
+function positiveInteger(value, label) {
+    if (!Number.isInteger(value) || value <= 0)
+        throw new Error(`${label} must be a positive integer`);
+    return value;
+}
+//# sourceMappingURL=timing.js.map

package/dist/timing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timing.js","sourceRoot":"","sources":["../src/timing.ts"],"names":[],"mappings":"AAmBA,MAAM,UAAU,sBAAsB,CAAC,MAAoC;IACzE,MAAM,cAAc,GAAG,eAAe,CAAC,MAAM,CAAC,cAAc,EAAE,gBAAgB,CAAC,CAAC;IAChF,MAAM,gBAAgB,GAAG,eAAe,CAAC,MAAM,CAAC,gBAAgB,EAAE,kBAAkB,CAAC,CAAC;IACtF,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,IAAI,GAAG,CAAC;IACxC,IAAI,QAAQ,IAAI,CAAC,IAAI,QAAQ,GAAG,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;IAEpF,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,cAAc,EAAE,gBAAgB,CAAC,GAAG,gBAAgB,CAAC;IAC/E,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC3C,MAAM,cAAc,GAAG,IAAI,CAAC,KAAK,CAAC,gBAAgB,GAAG,KAAK,CAAC,CAAC;IAC5D,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,cAAc,GAAG,cAAc,CAAC,CAAC;IAChE,MAAM,EAAE,GAAG,CAAC,KAAa,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC;IACxD,MAAM,KAAK,GAAG,CAAC,KAAa,EAAE,GAAW,EAAoB,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACrF,MAAM,OAAO,GAAG,CAAC,SAAiB,EAAE,KAAa,EAAE,WAAmB,EAAE,EAAE,CAAC,EAAE,CAAC,SAAS,GAAG,KAAK,GAAG,WAAW,CAAC,CAAC;IAC/G,MAAM,SAAS,GAAG,CAAC,SAAiB,EAAE,EAAE,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,GAAG,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;IAEnF,OAAO;QACL,cAAc;QACd,gBAAgB;QAChB,cAAc;QACd,KAAK;QACL,UAAU;QACV,EAAE;QACF,KAAK,EAAE,EAAE;QACT,KAAK;QACL,OAAO;QACP,SAAS;KACV,CAAC;AACJ,CAAC;AAOD,MAAM,UAAU,qBAAqB,CACnC,KAAa,EACb,GAAW,EACX,KAAa,EACb,QAA0B;IAE1B,OAAO;QACL,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;QAC9C,GAAG,EAAE,QAAQ,CAAC,SAAS,CAAC,GAAG,CAAC;KAC7B,CAAC;AACJ,CAAC;AAED,SAAS,eAAe,CAAC,KAAa,EAAE,KAAa;IACnD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,6BAA6B,CAAC,CAAC;IACnG,OAAO,KAAK,CAAC;AACf,CAAC"}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@promptframe/component-kit",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./standard": {
+      "import": "./dist/standard.js",
+      "types": "./dist/standard.d.ts"
+    },
+    "./preview": {
+      "import": "./dist/preview.js",
+      "types": "./dist/preview.d.ts"
+    },
+    "./timing": {
+      "import": "./dist/timing.js",
+      "types": "./dist/timing.d.ts"
+    },
+    "./package.json": {
+      "default": "./package.json"
+    }
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ty-teams/promptframe-component-kit.git",
+    "directory": "packages/component-kit"
+  },
+  "bugs": {
+    "url": "https://github.com/ty-teams/promptframe-component-kit/issues"
+  },
+  "homepage": "https://github.com/ty-teams/promptframe-component-kit#readme",
+  "scripts": {
+    "build": "tsc",
+    "lint": "tsc --noEmit",
+    "test": "node --import tsx --test test/*.test.ts",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "remotion": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "remotion": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "tsx": "^4.19.0",
+    "typescript": "~5.7.0"
+  }
+}