@warpgogol/forge 0.13.0 → 0.15.0

package/profiles/editframe-templates/composition-agents.md

@@ -0,0 +1,70 @@
+# Composition Workspace
+
+This workspace contains an Editframe video composition.
+
+## Domain terminology
+
+- **Composition** — the artifact this workspace produces (a `.tsx` file using `@editframe/react` components).
+- **Scene** — a structural module within a composition (a `Timegroup` block).
+- **Director** — the operator who creates and renders the composition.
+
+## Quality invariants
+
+| ID | Description | Severity |
+| --- | --- | --- |
+| VIDEO-01 | Composition filenames must use kebab-case (lowercase letters, digits, hyphens only). | error |
+| VIDEO-02 | Scene durations must use `contain` fit mode by default to avoid unexpected cropping. Use `cover` or `fill` only when intentionally overriding. | warning |
+| VIDEO-03 | All speech audio elements (`Audio` with speech content) must have corresponding `Captions` components for accessibility. | error |
+
+Additional time model invariants (VIDEO-04 through VIDEO-09) may be available. Run `forge doctor` to check the full invariant set enforced by the active profile.
+
+## Time model concepts
+
+Editframe compositions use a time model based on `Timegroup` components from `@editframe/react`:
+
+- **`TimelineRoot`** — the root container for the composition.
+- **`Timegroup`** — a container that groups scenes and controls timing. The root Timegroup defines the composition's total duration.
+- **`mode`** — timing behavior for children: `sequence` (play one after another), `fixed` (play at absolute offset), `contain` (fit within parent duration), `fit` (scale to fit).
+- **`duration`** — CSS time string (e.g. `5s`, `300ms`, `2.5s`) defining how long the element plays.
+- **`offset`** — CSS time string defining when the element starts relative to its parent.
+- **`fps`** — positive integer defining frames per second (e.g. `30`, `60`).
+- **`loop`** — boolean, only on the root Timegroup. Nested Timegroups should not loop.
+
+## Workflow
+
+1. Create a `.tsx` file with `@editframe/react` components (`TimelineRoot`, `Timegroup`, `Video`, `Audio`, `Text`, `Captions`).
+2. Run `editframe preview` to preview the composition in the browser.
+3. Run `ef-composition-review` to review the composition for time model correctness, accessibility, and best practices.
+4. Run `editframe check` to validate the composition structure.
+5. Run `editframe render -o dist/<name>.mp4` to produce the final video output.
+6. Run `ef-render-verify` to verify the render — validation, build, determinism, output inspection.
+
+## Skills
+
+- **ef-onboard** — onboard a new project: prerequisites, discovery, scaffold, preview. Trigger: "create a new video project".
+- **ef-composition-review** — review a composition for time model correctness, accessibility, and best practices before rendering. Trigger: "review this composition".
+- **ef-render-verify** — verify a render: validate, build, check determinism, inspect output. Trigger: "render and verify".
+- **ef-composition** — guide creating a new video composition with Editframe React components. Trigger: "create a video composition".
+- **ef-dev-server** — set up and manage the Editframe dev server for live preview. Trigger: "set up editframe dev server".
+- **ef-editor-gui** — configure the Editframe editor GUI for visual composition editing. Trigger: "open editframe editor".
+- **ef-webhooks** — configure Editframe webhooks for render status notifications. Trigger: "set up editframe webhooks".
+- **ef-brand-video-generator** — generate brand video compositions from templates. Trigger: "generate a brand video".
+- **ef-motion-design** — apply motion design patterns to compositions. Trigger: "add motion design".
+
+## External resources
+
+- [Editframe llms.txt](https://editframe.com/llms.txt) — machine-readable index of Editframe domain skills
+- [Editframe composition skill](https://editframe.com/skills/composition.md) — full reference for time model, elements, and rendering
+- [Editframe getting started](https://editframe.com/getting-started) — step-by-step guide and agent prompt
+
+## Reference template
+
+A sample composition template is available at `editframe-templates/composition.tsx` in the forge profiles directory. Copy it to start a new composition:
+
+```sh
+cp node_modules/@warpgogol/forge/profiles/editframe-templates/composition.tsx compositions/my-new-video/composition.tsx
+```
+
+## File naming
+
+Composition files use kebab-case: `my-video.tsx`, `product-demo.tsx`, `intro-clip.tsx`.

package/profiles/editframe-templates/composition.tsx

@@ -0,0 +1,33 @@
+/*
+  Editframe React composition template
+  Copy this file to start a new composition. @editframe/react components:
+  - TimelineRoot: root container for the composition
+  - Timegroup: groups elements into a timed sequence
+  - Video: video source with fit mode (contain, cover, fill)
+  - Audio: audio source
+  - Text: text overlay with positioning
+  - Captions: accessibility captions for speech audio
+  Run `editframe preview` to preview, `editframe render` to produce output.
+*/
+import { TimelineRoot, Timegroup, Video, Text, Audio, Captions } from "@editframe/react";
+
+export default function Composition() {
+  return (
+    <TimelineRoot>
+      <Timegroup duration="10s">
+        <Video src="assets/background.mp4" fit="contain" duration="10s" />
+        <Text
+          text="Your text here"
+          x="50%"
+          y="50%"
+          fontSize="48px"
+          color="white"
+          textAlign="center"
+          duration="5s"
+        />
+        <Audio src="assets/narration.mp3" />
+        <Captions src="assets/captions.vtt" />
+      </Timegroup>
+    </TimelineRoot>
+  );
+}

package/profiles/editframe-templates/html-composition-agents.md

@@ -0,0 +1,62 @@
+# HTML Composition Workspace
+
+This workspace contains an Editframe video composition using HTML web components.
+
+## Domain terminology
+
+- **Composition** — the artifact this workspace produces (an `.html` file using Editframe web components).
+- **Scene** — a structural module within a composition (an `ef-timegroup` block).
+- **Director** — the operator who creates and renders the composition.
+
+## Quality invariants
+
+| ID | Description | Severity |
+| --- | --- | --- |
+| VIDEO-01 | Composition filenames must use kebab-case (lowercase letters, digits, hyphens only). | error |
+| VIDEO-02 | Scene durations must use `contain` fit mode by default to avoid unexpected cropping. Use `cover` or `fill` only when intentionally overriding. | warning |
+| VIDEO-03 | All speech audio elements (`ef-audio` with speech content) must have corresponding `ef-captions` components for accessibility. | error |
+
+Additional time model invariants (VIDEO-04 through VIDEO-09) may be available. Run `forge doctor` to check the full invariant set enforced by the active profile.
+
+## Time model concepts
+
+Editframe HTML compositions use a time model based on web components:
+
+- **`ef-timeline`** — the root container for the composition.
+- **`ef-timegroup`** — a container that groups scenes and controls timing. The root ef-timegroup defines the composition's total duration.
+- **`mode`** — timing behavior for children: `sequence` (play one after another), `fixed` (play at absolute offset), `contain` (fit within parent duration), `fit` (scale to fit).
+- **`duration`** — CSS time string (e.g. `5s`, `300ms`, `2.5s`) defining how long the element plays.
+- **`offset`** — CSS time string defining when the element starts relative to its parent.
+- **`fps`** — positive integer defining frames per second (e.g. `30`, `60`).
+- **`loop`** — boolean, only on the root ef-timegroup. Nested ef-timegroups should not loop.
+
+## Workflow
+
+1. Create an `.html` file with Editframe web components (`ef-timeline`, `ef-timegroup`, `ef-video`, `ef-audio`, `ef-text`, `ef-captions`).
+2. Run `editframe preview` to preview the composition in the browser.
+3. Run `ef-composition-review` to review the composition for time model correctness, accessibility, and best practices.
+4. Run `editframe check` to validate the composition structure.
+5. Run `editframe render -o dist/<name>.mp4` to produce the final video output.
+6. Run `ef-render-verify` to verify the render — validation, build, determinism, output inspection.
+
+## Skills
+
+- **ef-onboard** — onboard a new project: prerequisites, discovery, scaffold, preview. Trigger: "create a new video project".
+- **ef-composition-review** — review a composition for time model correctness, accessibility, and best practices before rendering. Trigger: "review this composition".
+- **ef-render-verify** — verify a render: validate, build, check determinism, inspect output. Trigger: "render and verify".
+- **ef-composition** — guide creating a new video composition with Editframe HTML components. Trigger: "create a video composition".
+- **ef-dev-server** — set up and manage the Editframe dev server for live preview. Trigger: "set up editframe dev server".
+- **ef-editor-gui** — configure the Editframe editor GUI for visual composition editing. Trigger: "open editframe editor".
+- **ef-webhooks** — configure Editframe webhooks for render status notifications. Trigger: "set up editframe webhooks".
+- **ef-brand-video-generator** — generate brand video compositions from templates. Trigger: "generate a brand video".
+- **ef-motion-design** — apply motion design patterns to compositions. Trigger: "add motion design".
+
+## External resources
+
+- [Editframe llms.txt](https://editframe.com/llms.txt) — machine-readable index of Editframe domain skills
+- [Editframe composition skill](https://editframe.com/skills/composition.md) — full reference for time model, elements, and rendering
+- [Editframe getting started](https://editframe.com/getting-started) — step-by-step guide and agent prompt
+
+## File naming
+
+Composition files use kebab-case: `my-video.html`, `product-demo.html`, `intro-clip.html`.

package/profiles/{editframe-html.yaml → editframe.yaml}

@@ -1,6 +1,6 @@
 schema: forge/stack-profile@1
-id: editframe-html
-displayName: Editframe HTML Video
+id: editframe
+displayName: Editframe Video
 detect:
   anyOf:
     - editframe.config.*
@@ -20,8 +20,8 @@ devServer:
 artifacts:
   - id: composition
     extensions:
-      - .html
       - .tsx
+      - .html
     produce:
       command: editframe render
       output: dist/{composition}.mp4
@@ -30,6 +30,7 @@ artifacts:
     determinism:
       hashable: true
       inputs:
+        - compositions/**/*.tsx
         - compositions/**/*.html
         - assets/**
 assets:
@@ -48,38 +49,118 @@ release:
   target: local
   outputDir: release
   manifestName: release-manifest.json
+prerequisites:
+  - id: nodejs
+    name: Node.js 18+
+    check: node --version
+    installHint: "https://nodejs.org/en/download/"
+    severity: error
+  - id: ffmpeg
+    name: FFmpeg
+    check: ffmpeg -version
+    installHint: "https://ffmpeg.org/download.html"
+    severity: error
 workspaceTypes:
   - id: composition
+    detect:
+      glob: "*.tsx"
+      contains: TimelineRoot
+      packageJsonDep: "@editframe/react"
+    skills:
+      - ef-onboard
+      - ef-composition-review
+      - ef-render-verify
+    agentsMdTemplate: editframe-templates/composition-agents.md
+  - id: html-composition
     detect:
       glob: "*.html"
       contains: ef-timegroup
       packageJsonDep: "@editframe/cli"
     skills:
+      - ef-onboard
       - ef-composition-review
       - ef-render-verify
-    agentsMdTemplate: editframe-html-templates/composition-agents.md
+    agentsMdTemplate: editframe-templates/html-composition-agents.md
 invariants:
   - id: VIDEO-01
     rule: Composition filenames must use kebab-case (lowercase letters, digits, hyphens only)
     severity: error
     check:
       kind: filename-pattern
-      glob: "compositions/**/*.{html,tsx}"
-      pattern: "^[a-z0-9-]+\\.(html|tsx)$"
+      glob: "compositions/**/*.{tsx,html}"
+      pattern: "^[a-z0-9-]+\\.(tsx|html)$"
   - id: VIDEO-02
     rule: Scene durations must use contain mode by default to avoid unexpected cropping
     severity: warning
     check:
       kind: file-contains
-      glob: "compositions/**/*.html"
+      glob: "compositions/**/*.{tsx,html}"
       pattern: contain
   - id: VIDEO-03
-    rule: All speech audio elements must have corresponding ef-captions elements for accessibility
+    rule: All speech audio elements must have corresponding Captions components for accessibility
+    severity: error
+    check:
+      kind: file-contains
+      glob: "compositions/**/*.{tsx,html}"
+      pattern: Captions
+  - id: VIDEO-04
+    rule: Root Timegroup must declare duration or use mode="contain" or mode="fit"
     severity: error
     check:
       kind: file-contains
-      glob: "compositions/**/*.html"
-      pattern: ef-captions
+      glob: "compositions/**/*.{tsx,html}"
+      pattern: 'Timegroup[^>]*(duration|mode="contain"|mode="fit")[^>]*>|ef-timegroup[^>]*(duration|mode="contain"|mode="fit")[^>]*>'
+  - id: VIDEO-05
+    rule: All duration values must be valid CSS time strings (e.g. 5s, 500ms, 2.5s)
+    severity: error
+    check:
+      kind: attribute-pattern
+      glob: "compositions/**/*.{tsx,html}"
+      elements:
+        - ef-timegroup
+        - Timegroup
+      attribute: "duration"
+      pattern: "^\\d+(\\.\\d+)?(s|ms)$"
+  - id: VIDEO-06
+    rule: "mode attribute must be one of: sequence, fixed, contain, fit"
+    severity: error
+    check:
+      kind: attribute-pattern
+      glob: "compositions/**/*.{tsx,html}"
+      elements:
+        - ef-timegroup
+        - Timegroup
+      attribute: "mode"
+      pattern: "^(sequence|fixed|contain|fit)$"
+  - id: VIDEO-07
+    rule: fps must be a positive integer (default 30)
+    severity: warning
+    check:
+      kind: attribute-pattern
+      glob: "compositions/**/*.{tsx,html}"
+      elements:
+        - ef-timegroup
+        - Timegroup
+      attribute: "fps"
+      pattern: "^[1-9]\\d*$"
+  - id: VIDEO-08
+    rule: loop attribute should only be used on the root Timegroup (no effect on render for nested groups)
+    severity: warning
+    check:
+      kind: file-not-contains
+      glob: "compositions/**/*.{tsx,html}"
+      negatedPattern: "<(Timegroup|ef-timegroup)[^>]*loop[^>]*>[\\s\\S]*<(Timegroup|ef-timegroup)[^>]*loop"
+  - id: VIDEO-09
+    rule: offset values must be valid CSS time strings (e.g. 0.5s, 3s, 500ms)
+    severity: warning
+    check:
+      kind: attribute-pattern
+      glob: "compositions/**/*.{tsx,html}"
+      elements:
+        - ef-timegroup
+        - Timegroup
+      attribute: "offset"
+      pattern: "^\\d+(\\.\\d+)?(s|ms)$"
 workspace:
   dirs:
     - compositions
@@ -280,34 +361,118 @@ firstWorkspace:
             "check": "editframe check"
           }
         }
-    - path: composition.html
+    - path: composition.tsx
       content: |
-        <!--
-          Editframe HTML composition — my-first-video
-          This file declares a video composition using Editframe custom elements.
+        /*
+          Editframe React composition — my-first-video
+          This file declares a video composition using @editframe/react components.
           Run `editframe preview` to preview, `editframe render` to produce output.
-        -->
-        <ef-timegroup duration="10s">
-          <ef-video
-            src="assets/background.mp4"
-            fit="contain"
-            duration="10s"
-          ></ef-video>
-          <ef-text
-            text="Hello, Editframe!"
-            x="50%"
-            y="50%"
-            font-size="48px"
-            color="white"
-            text-align="center"
-            duration="5s"
-          ></ef-text>
-          <ef-audio
-            src="assets/narration.mp3"
-          ></ef-audio>
-          <ef-captions
-            src="assets/captions.vtt"
-          ></ef-captions>
-        </ef-timegroup>
+        */
+        import { TimelineRoot, Timegroup, Video, Text, Audio, Captions } from "@editframe/react";
+
+        export default function Composition() {
+          return (
+            <TimelineRoot>
+              <Timegroup duration="10s">
+                <Video src="assets/background.mp4" fit="contain" duration="10s" />
+                <Text
+                  text="Hello, Editframe!"
+                  x="50%"
+                  y="50%"
+                  fontSize="48px"
+                  color="white"
+                  textAlign="center"
+                  duration="5s"
+                />
+                <Audio src="assets/narration.mp3" />
+                <Captions src="assets/captions.vtt" />
+              </Timegroup>
+            </TimelineRoot>
+          );
+        }
   install:
-    - pnpm add -D vitest
+    - pnpm add -D @editframe/react @editframe/vite-plugin react react-dom typescript @types/react @types/react-dom vite @vitejs/plugin-react tailwindcss @tailwindcss/vite vitest
+templates:
+  - id: react
+    default: true
+    firstWorkspace:
+      path: compositions/my-first-video
+      files:
+        - path: package.json
+          content: |
+            {
+              "name": "my-first-video",
+              "version": "0.1.0",
+              "private": true,
+              "type": "module",
+              "scripts": {
+                "preview": "editframe preview",
+                "render": "editframe render -o dist/my-first-video.mp4",
+                "check": "editframe check"
+              }
+            }
+        - path: composition.tsx
+          content: |
+            /*
+              Editframe React composition — my-first-video
+              This file declares a video composition using @editframe/react components.
+              Run `editframe preview` to preview, `editframe render` to produce output.
+            */
+            import { TimelineRoot, Timegroup, Video, Text, Audio, Captions } from "@editframe/react";
+
+            export default function Composition() {
+              return (
+                <TimelineRoot>
+                  <Timegroup duration="10s">
+                    <Video src="assets/background.mp4" fit="contain" duration="10s" />
+                    <Text
+                      text="Hello, Editframe!"
+                      x="50%"
+                      y="50%"
+                      fontSize="48px"
+                      color="white"
+                      textAlign="center"
+                      duration="5s"
+                    />
+                    <Audio src="assets/narration.mp3" />
+                    <Captions src="assets/captions.vtt" />
+                  </Timegroup>
+                </TimelineRoot>
+              );
+            }
+      install:
+        - pnpm add -D @editframe/react @editframe/vite-plugin react react-dom typescript @types/react @types/react-dom vite @vitejs/plugin-react tailwindcss @tailwindcss/vite vitest
+  - id: html
+    firstWorkspace:
+      path: compositions/my-first-video
+      files:
+        - path: package.json
+          content: |
+            {
+              "name": "my-first-video",
+              "version": "0.1.0",
+              "private": true,
+              "type": "module",
+              "scripts": {
+                "preview": "editframe preview",
+                "render": "editframe render -o dist/my-first-video.mp4",
+                "check": "editframe check"
+              }
+            }
+        - path: index.html
+          content: |
+            <!--
+              Editframe HTML composition — my-first-video
+              This file declares a video composition using Editframe web components.
+              Run `editframe preview` to preview, `editframe render` to produce output.
+            -->
+            <ef-timeline duration="10s">
+              <ef-timegroup duration="10s" mode="contain">
+                <ef-video src="assets/background.mp4" fit="contain" duration="10s"></ef-video>
+                <ef-text text="Hello, Editframe!" x="50%" y="50%" font-size="48px" color="white" text-align="center" duration="5s"></ef-text>
+                <ef-audio src="assets/narration.mp3"></ef-audio>
+                <ef-captions src="assets/captions.vtt"></ef-captions>
+              </ef-timegroup>
+            </ef-timeline>
+      install:
+        - pnpm add -D vitest

package/skills/fo/ef-brand-video-generator/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: ef-brand-video-generator
+description: "Generate brand video compositions from templates — logo animation, intro/outro, brand colors, typography. Use when the operator asks to generate a brand video."
+invocation: user
+category: fo
+concerns: content-mutation
+dependsOn: []
+languagePolicy: ref(PREFERENCES.md)
+triggers:
+  - "generate a brand video"
+  - "create a logo animation"
+  - "brand intro video"
+  - "brand outro video"
+source: domain-knowledge
+---
+
+<!-- skill-lint-disable SKILL-17 -->
+
+Before starting, read `PREFERENCES.md` at the repository root. If the file is missing or `aiLanguage` is unset, ask the operator once and create the file using the `my-preferences` skill semantics.
+
+# Brand Video Generator
+
+Generate brand video compositions from reusable templates. Brand videos typically include logo animations, intro/outro sequences, brand color overlays, and typography that matches brand guidelines.
+
+## Template structure
+
+A brand video composition uses `@editframe/react` components with brand-specific assets:
+
+```tsx
+import { TimelineRoot, Timegroup, Video, Image, Text } from "@editframe/react";
+
+export default function BrandIntro() {
+  return (
+    <TimelineRoot>
+      <Timegroup duration="3s" mode="sequence">
+        <Image src="assets/logo.svg" duration="1s" fit="contain" />
+        <Text
+          text="Your Brand"
+          x="50%"
+          y="50%"
+          fontSize="64px"
+          color="#FF6B00"
+          duration="1s"
+        />
+        <Video src="assets/brand-bg.mp4" fit="cover" duration="1s" />
+      </Timegroup>
+    </TimelineRoot>
+  );
+}
+```
+
+## Brand asset checklist
+
+- **Logo** — SVG or PNG with transparent background
+- **Brand colors** — primary, secondary, accent as CSS color values
+- **Typography** — brand font family, weights, sizes
+- **Background video** — optional branded background clip
+- **Audio** — optional brand jingle or voiceover
+
+## Common brand video patterns
+
+### Logo animation
+
+Animate the logo in with a `Timegroup` using `mode="sequence"`:
+
+```tsx
+<Timegroup duration="2s" mode="sequence">
+  <Image src="assets/logo.svg" duration="0.5s" fit="contain" />
+  <Text text="Your Brand" fontSize="48px" color="#FF6B00" duration="1.5s" />
+</Timegroup>
+```
+
+### Intro/outro pair
+
+Create separate compositions for intro and outro, then combine them in a parent `Timegroup`:
+
+```tsx
+<TimelineRoot>
+  <Timegroup duration="15s" mode="sequence">
+    <BrandIntro />
+    <MainContent />
+    <BrandOutro />
+  </Timegroup>
+</TimelineRoot>
+```
+
+### Brand color overlay
+
+Use a semi-transparent `Image` or `Text` overlay with brand colors:
+
+```tsx
+<Image src="assets/brand-overlay.png" duration="10s" fit="cover" />
+```
+
+## Rendering
+
+Run `ref(forge.yaml bindings.commands.build)` to render the brand video. Use `ref(forge.yaml bindings.commands.validate)` to check the composition before rendering.
+
+## Customization
+
+Each brand video template accepts parameters for logo, colors, text, and timing. Adjust the `duration`, `mode`, and asset paths to match the brand guidelines.