Code-first video & image, rendered natively on WebGPU.
Prepare gitframes plugin for Anthropic's plugin directory
okanaslab4b247aebb6
diff --git a/.agent/rules/general-information.md b/.agent/rules/general-information.mdindex 9083ae5e..97813101 100644--- a/.agent/rules/general-information.md+++ b/.agent/rules/general-information.md@@ -32,7 +32,7 @@ Gitframes is a code-first video engine on native WebGPU (Dawn) in Node, with no- `nodes/node-*` (59): one VFX/audio/layout node each. Layout: `src/shared/` (config and schema), `src/renderers/` (WebGPU), `src/index.ts`. Only `node-compositor` has a `SKILL.md`; update it when Compositor behavior changes (`packages/compositions/src/program/skillmd-check.test.ts` guards it).- `apps/renderer-service`: HTTP render service (Docker, RunPod worker).- `examples/NN_*`: reference films/ads that import `gitframes` via workspace. Study `19_gitframes_film` (best structure), `22_gitframes_launch` before writing a new film.-- `skills/gitframes-{compose,effects,render}`: agent skills, symlinked from `.agents/skills` and `.claude/skills`.+- `plugins/gitframes/skills/gitframes-{compose,effects,render}`: agent skills, symlinked from `.agents/skills` and `.claude/skills`.- `examples/22_gitframes_launch`: reference for a lyric-driven launch film.- Package `exports` have a `development` condition pointing at `src/`. Otherwise consumers resolve `dist/`, so run `pnpm build` after changing a dependency.@@ -42,7 +42,7 @@ Gitframes is a code-first video engine on native WebGPU (Dawn) in Node, with no- Test: `pnpm --filter <name> test` (vitest; `packages/renderer` uses `test:vitest`). Root `pnpm test` runs everything and is slow.- Lint and format: `pnpm exec biome check --write <files>` (lefthook runs it on commit).- Example: `pnpm --filter @gitframes/example-19-gitframes-film assets|render|test|typecheck`.-- Agent skills: after changing engine API behavior, update the owning skill or reference, then run `pnpm run check:plugins`. `skills/gitframes-effects/references/effects-catalog.md` is generated by `pnpm run sync:effects-catalog`; never hand-edit it.+- Agent skills: after changing engine API behavior, update the owning skill or reference, then run `pnpm run check:plugins`. `plugins/gitframes/skills/gitframes-effects/references/effects-catalog.md` is generated by `pnpm run sync:effects-catalog`; never hand-edit it.- Version bumps: use changesets (`.changeset/`).## Ignored, local-only files@@ -83,7 +83,7 @@ Fonts (`assets/fonts`), `*.mp4/mp3/wav/png/jpg`, `*.onnx`, `scratch*/`, `example## Video taste-Follow `skills/gitframes-compose/SKILL.md`. Build like a designer with an engineer's discipline.+Follow `plugins/gitframes/skills/gitframes-compose/SKILL.md`. Build like a designer with an engineer's discipline.- **Tokens first:** `theme.ts` with palette, type scale, spacing, radii, eases, and one `BEAT` constant.- **Native layout trees only:** Never fake a UI, chart or screenshot with a pre-rendered bitmap.diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.jsonindex 9f79c89c..c10aeb23 100644--- a/.agents/plugins/marketplace.json+++ b/.agents/plugins/marketplace.json@@ -5,7 +5,7 @@"name": "gitframes","source": {"source": "local",- "path": "./"+ "path": "./plugins/gitframes"},"policy": {"installation": "AVAILABLE",diff --git a/.agents/skills/gitframes-compose b/.agents/skills/gitframes-composeindex be4097a9..b6524a2f 120000--- a/.agents/skills/gitframes-compose+++ b/.agents/skills/gitframes-compose@@ -1 +1 @@-../../skills/gitframes-compose\ No newline at end of file+../../plugins/gitframes/skills/gitframes-compose\ No newline at end of filediff --git a/.agents/skills/gitframes-effects b/.agents/skills/gitframes-effectsindex bd85f7d5..0c7d4021 120000--- a/.agents/skills/gitframes-effects+++ b/.agents/skills/gitframes-effects@@ -1 +1 @@-../../skills/gitframes-effects\ No newline at end of file+../../plugins/gitframes/skills/gitframes-effects\ No newline at end of filediff --git a/.agents/skills/gitframes-render b/.agents/skills/gitframes-renderindex bdbc663f..8e118623 120000--- a/.agents/skills/gitframes-render+++ b/.agents/skills/gitframes-render@@ -1 +1 @@-../../skills/gitframes-render\ No newline at end of file+../../plugins/gitframes/skills/gitframes-render\ No newline at end of filediff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.jsonindex ef4a07c9..a2b1cca4 100644--- a/.claude-plugin/marketplace.json+++ b/.claude-plugin/marketplace.json@@ -8,12 +8,7 @@"plugins": [{"name": "gitframes",- "source": "./",- "skills": [- "./skills/gitframes-compose",- "./skills/gitframes-effects",- "./skills/gitframes-render"- ],+ "source": "./plugins/gitframes","description": "Author, render and verify video compositions with the gitframes WebGPU SDK.","category": "design"}diff --git a/.claude/skills/gitframes-compose b/.claude/skills/gitframes-composeindex be4097a9..b6524a2f 120000--- a/.claude/skills/gitframes-compose+++ b/.claude/skills/gitframes-compose@@ -1 +1 @@-../../skills/gitframes-compose\ No newline at end of file+../../plugins/gitframes/skills/gitframes-compose\ No newline at end of filediff --git a/.claude/skills/gitframes-effects b/.claude/skills/gitframes-effectsindex bd85f7d5..0c7d4021 120000--- a/.claude/skills/gitframes-effects+++ b/.claude/skills/gitframes-effects@@ -1 +1 @@-../../skills/gitframes-effects\ No newline at end of file+../../plugins/gitframes/skills/gitframes-effects\ No newline at end of filediff --git a/.claude/skills/gitframes-render b/.claude/skills/gitframes-renderindex bdbc663f..8e118623 120000--- a/.claude/skills/gitframes-render+++ b/.claude/skills/gitframes-render@@ -1 +1 @@-../../skills/gitframes-render\ No newline at end of file+../../plugins/gitframes/skills/gitframes-render\ No newline at end of filediff --git a/.gitignore b/.gitignoreindex 62117f7f..bb1bdd91 100644--- a/.gitignore+++ b/.gitignore@@ -49,8 +49,9 @@ assets/soundfonts/*.png*.jpg*.jpeg-# ...except the brand assets the README links to+# ...except the brand assets the README links to and the plugin icon!assets/brand/*.png+!plugins/gitframes/assets/*.png# Vision Tracking Caches*tracking.jsondiff --git a/README.md b/README.mdindex b3cda2f2..3338486c 100644--- a/README.md+++ b/README.md@@ -6,11 +6,14 @@[](https://www.npmjs.com/package/gitframes)[](LICENCE)+[](#)[](https://nodejs.org)[](https://www.w3.org/TR/webgpu/)[](#monorepo-architecture)[](#6-on-device-vision--tracking)+> **⚠️ Beta:** gitframes is under active development. APIs may change between releases and some features may be incomplete or unstable.+**Code-first video as pure software engineering** — no headless browser, no DOM reflow, no screenshot pipeline.Renders directly on GPU hardware via Dawn / WebGPU / Metal / Vulkan in Node.js and modern WebGPU browsers.@@ -24,6 +27,7 @@ Renders directly on GPU hardware via Dawn / WebGPU / Metal / Vulkan in Node.js a> /plugin marketplace add gatewai-dev/gitframes> /plugin install gitframes@gitframes-plugins> ```+> Run these in a `claude` terminal session (not the desktop app's Code tab), then restart or run `/reload-plugins`.>> **Codex**> ```bash@@ -233,7 +237,7 @@ gitframes/├── apps/│ └── renderer-service/ # Production HTTP / gRPC rendering microservice container├── examples/ # Reference compositions and films-├── skills/ # Portable agent skills (compose, effects, render)+├── plugins/gitframes/ # Agent plugin: skills only (compose, effects, render)└── scripts/ # Build, release, and plugin validation tooling```@@ -534,6 +538,10 @@ Gitframes ships agent skills that teach Claude, Codex, and other coding agents hOnce installed, skills load automatically when a task matches (e.g. *"add a film-grain pass to this scene"* or *"render a frame grid of intro.ts"*).+### What the plugin runs and sends++The plugin is instructions only. It bundles no executables, MCP servers, hooks, or package launchers, and it sends no data anywhere. The skills tell your agent to add the [`gitframes`](https://www.npmjs.com/package/gitframes) npm package to your project and how to use it. When that code uses on-device vision, the SDK downloads the pinned model weights from Hugging Face on first use (see [On-Device Vision](#6-on-device-vision--tracking)). Nothing else leaves your machine.+### Claude Code```text@@ -548,6 +556,8 @@ claude plugin marketplace add gatewai-dev/gitframesclaude plugin install gitframes@gitframes-plugins```+Adding the marketplace only registers the catalog; the `install` step is what enables the skills. Afterwards, restart Claude Code or run `/reload-plugins`. `/plugin` commands need an interactive `claude` terminal — they don't work in the desktop app's Code tab, so use the shell form there.+Add `--scope project` to record the plugin in `.claude/settings.json` for the whole team. Update later with `/plugin marketplace update gitframes-plugins`.**Enable it for everyone in your repo.** Commit this to `.claude/settings.json`; Claude Code prompts teammates to install it when they trust the folder:@@ -588,13 +598,13 @@ With the [`skills`](https://skills.sh) CLI, which supports Claude Code, Codex, Cnpx skills add gatewai-dev/gitframes```-Or copy the folders by hand: put `skills/<name>/` into `.claude/skills/`, `.agents/skills/`, or `~/.agents/skills/`. VS Code / Copilot / Cursor / Kiro can load the portable root [`plugin.json`](plugin.json) through their plugin UI.+Or copy the folders by hand: put `plugins/gitframes/skills/<name>/` into `.claude/skills/`, `.agents/skills/`, or `~/.agents/skills/`. VS Code / Copilot / Cursor / Kiro can load the portable [`plugin.json`](plugins/gitframes/plugin.json) through their plugin UI.### Maintaining the plugin-Three manifests describe the same plugin: [`plugin.json`](plugin.json) (portable [Agent Plugins 1.0](https://agent-plugins.org)), [`.claude-plugin/plugin.json`](.claude-plugin/plugin.json), and [`.codex-plugin/plugin.json`](.codex-plugin/plugin.json). The marketplace catalogs are [`.claude-plugin/marketplace.json`](.claude-plugin/marketplace.json) and [`.agents/plugins/marketplace.json`](.agents/plugins/marketplace.json). The portable field set is closed — client-specific fields go in that client's manifest, not in `plugin.json`. Bump `version` in all three together, since clients use it to decide when to update.+The plugin lives in [`plugins/gitframes/`](plugins/gitframes) so installs carry only the skills; users get the engine from npm. Three manifests there describe it: [`plugin.json`](plugins/gitframes/plugin.json) (portable [Agent Plugins 1.0](https://agent-plugins.org)), [`.claude-plugin/plugin.json`](plugins/gitframes/.claude-plugin/plugin.json), and [`.codex-plugin/plugin.json`](plugins/gitframes/.codex-plugin/plugin.json). The marketplace catalogs are [`.claude-plugin/marketplace.json`](.claude-plugin/marketplace.json) and [`.agents/plugins/marketplace.json`](.agents/plugins/marketplace.json). The portable field set is closed — client-specific fields go in that client's manifest, not in `plugin.json`. The `version` in all three follows the `gitframes` package: `pnpm run version:packages` syncs it after `changeset version` (or run `pnpm run sync:plugin-version` on its own), since clients use it to decide when to update.-Inside this repository, Codex and Claude pick up skills through the symlinks in `.agents/skills/` and `.claude/skills/`. Skills live only under `skills/`; never copy them elsewhere. `pnpm run check:plugins` validates manifests, skill frontmatter, marketplace catalogs, symlinks, and the generated effects catalog. `pnpm run sync:effects-catalog` regenerates the `gitframes-effects` catalog after any `Effect` class change.+Inside this repository, Codex and Claude pick up skills through the symlinks in `.agents/skills/` and `.claude/skills/`. Skills live only under `plugins/gitframes/skills/`; never copy them elsewhere. `pnpm run check:plugins` validates manifests, skill frontmatter, marketplace catalogs, symlinks, and the generated effects catalog. `pnpm run sync:effects-catalog` regenerates the `gitframes-effects` catalog after any `Effect` class change.---diff --git a/package.json b/package.jsonindex d2d47234..f3c4fb90 100644--- a/package.json+++ b/package.json@@ -11,7 +11,8 @@"generate:effects": "tsx --conditions development scripts/generate-effects.mts","sync:effects-catalog": "node scripts/sync-effects-catalog.mjs","changeset": "changeset",- "version:packages": "changeset version",+ "version:packages": "changeset version && node scripts/sync-plugin-version.mjs",+ "sync:plugin-version": "node scripts/sync-plugin-version.mjs","release:local": "turbo run build && pnpm -r publish --access public --no-git-checks","release:local:dry-run": "turbo run build && pnpm -r publish --dry-run --access public --no-git-checks","release:gitframes": "turbo run build && pnpm --filter gitframes publish --access public --no-git-checks",diff --git a/.claude-plugin/plugin.json b/plugins/gitframes/.claude-plugin/plugin.jsonsimilarity index 73%rename from .claude-plugin/plugin.jsonrename to plugins/gitframes/.claude-plugin/plugin.jsonindex b4ea932f..16b438d8 100644--- a/.claude-plugin/plugin.json+++ b/plugins/gitframes/.claude-plugin/plugin.json@@ -2,13 +2,16 @@"$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json","name": "gitframes","displayName": "Gitframes",- "version": "0.1.0",+ "version": "1.3.1","description": "Author, render and verify video compositions with the gitframes WebGPU SDK.","author": {"name": "Gitframes","url": "https://github.com/gatewai-dev"},"license": "Apache-2.0",+ "icon": "./assets/logo.png",+ "documentationUrl": "https://github.com/gatewai-dev/gitframes#agent-skills--plugins",+ "supportUrl": "https://github.com/gatewai-dev/gitframes/issues","keywords": ["gitframes","webgpu",diff --git a/.codex-plugin/plugin.json b/plugins/gitframes/.codex-plugin/plugin.jsonsimilarity index 87%rename from .codex-plugin/plugin.jsonrename to plugins/gitframes/.codex-plugin/plugin.jsonindex 6e89e336..25322265 100644--- a/.codex-plugin/plugin.json+++ b/plugins/gitframes/.codex-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "gitframes",- "version": "0.1.0",+ "version": "1.3.1","description": "Author, render and verify video compositions with the gitframes WebGPU SDK.","skills": "./skills/"}diff --git a/plugins/gitframes/LICENSE b/plugins/gitframes/LICENSEnew file mode 100644index 00000000..c77b4278--- /dev/null+++ b/plugins/gitframes/LICENSE@@ -0,0 +1,202 @@++ Apache License+ Version 2.0, January 2004+ http://www.apache.org/licenses/++ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION++ 1. Definitions.++ "License" shall mean the terms and conditions for use, reproduction,+ and distribution as defined by Sections 1 through 9 of this document.++ "Licensor" shall mean the copyright owner or entity authorized by+ the copyright owner that is granting the License.++ "Legal Entity" shall mean the union of the acting entity and all+ other entities that control, are controlled by, or are under common+ control with that entity. For the purposes of this definition,+ "control" means (i) the power, direct or indirect, to cause the+ direction or management of such entity, whether by contract or+ otherwise, or (ii) ownership of fifty percent (50%) or more of the+ outstanding shares, or (iii) beneficial ownership of such entity.++ "You" (or "Your") shall mean an individual or Legal Entity+ exercising permissions granted by this License.++ "Source" form shall mean the preferred form for making modifications,+ including but not limited to software source code, documentation+ source, and configuration files.++ "Object" form shall mean any form resulting from mechanical+ transformation or translation of a Source form, including but+ not limited to compiled object code, generated documentation,+ and conversions to other media types.++ "Work" shall mean the work of authorship, whether in Source or+ Object form, made available under the License, as indicated by a+ copyright notice that is included in or attached to the work+ (an example is provided in the Appendix below).++ "Derivative Works" shall mean any work, whether in Source or Object+ form, that is based on (or derived from) the Work and for which the+ editorial revisions, annotations, elaborations, or other modifications+ represent, as a whole, an original work of authorship. For the purposes+ of this License, Derivative Works shall not include works that remain+ separable from, or merely link (or bind by name) to the interfaces of,+ the Work and Derivative Works thereof.++ "Contribution" shall mean any work of authorship, including+ the original version of the Work and any modifications or additions+ to that Work or Derivative Works thereof, that is intentionally+ submitted to Licensor for inclusion in the Work by the copyright owner+ or by an individual or Legal Entity authorized to submit on behalf of+ the copyright owner. For the purposes of this definition, "submitted"+ means any form of electronic, verbal, or written communication sent+ to the Licensor or its representatives, including but not limited to+ communication on electronic mailing lists, source code control systems,+ and issue tracking systems that are managed by, or on behalf of, the+ Licensor for the purpose of discussing and improving the Work, but+ excluding communication that is conspicuously marked or otherwise+ designated in writing by the copyright owner as "Not a Contribution."++ "Contributor" shall mean Licensor and any individual or Legal Entity+ on behalf of whom a Contribution has been received by Licensor and+ subsequently incorporated within the Work.++ 2. Grant of Copyright License. Subject to the terms and conditions of+ this License, each Contributor hereby grants to You a perpetual,+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable+ copyright license to reproduce, prepare Derivative Works of,+ publicly display, publicly perform, sublicense, and distribute the+ Work and such Derivative Works in Source or Object form.++ 3. Grant of Patent License. Subject to the terms and conditions of+ this License, each Contributor hereby grants to You a perpetual,+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable+ (except as stated in this section) patent license to make, have made,+ use, offer to sell, sell, import, and otherwise transfer the Work,+ where such license applies only to those patent claims licensable+ by such Contributor that are necessarily infringed by their+ Contribution(s) alone or by combination of their Contribution(s)+ with the Work to which such Contribution(s) was submitted. If You+ institute patent litigation against any entity (including a+ cross-claim or counterclaim in a lawsuit) alleging that the Work+ or a Contribution incorporated within the Work constitutes direct+ or contributory patent infringement, then any patent licenses+ granted to You under this License for that Work shall terminate+ as of the date such litigation is filed.++ 4. Redistribution. You may reproduce and distribute copies of the+ Work or Derivative Works thereof in any medium, with or without+ modifications, and in Source or Object form, provided that You+ meet the following conditions:++ (a) You must give any other recipients of the Work or+ Derivative Works a copy of this License; and++ (b) You must cause any modified files to carry prominent notices+ stating that You changed the files; and++ (c) You must retain, in the Source form of any Derivative Works+ that You distribute, all copyright, patent, trademark, and+ attribution notices from the Source form of the Work,+ excluding those notices that do not pertain to any part of+ the Derivative Works; and++ (d) If the Work includes a "NOTICE" text file as part of its+ distribution, then any Derivative Works that You distribute must+ include a readable copy of the attribution notices contained+ within such NOTICE file, excluding those notices that do not+ pertain to any part of the Derivative Works, in at least one+ of the following places: within a NOTICE text file distributed+ as part of the Derivative Works; within the Source form or+ documentation, if provided along with the Derivative Works; or,+ within a display generated by the Derivative Works, if and+ wherever such third-party notices normally appear. The contents+ of the NOTICE file are for informational purposes only and+ do not modify the License. You may add Your own attribution+ notices within Derivative Works that You distribute, alongside+ or as an addendum to the NOTICE text from the Work, provided+ that such additional attribution notices cannot be construed+ as modifying the License.++ You may add Your own copyright statement to Your modifications and+ may provide additional or different license terms and conditions+ for use, reproduction, or distribution of Your modifications, or+ for any such Derivative Works as a whole, provided Your use,+ reproduction, and distribution of the Work otherwise complies with+ the conditions stated in this License.++ 5. Submission of Contributions. Unless You explicitly state otherwise,+ any Contribution intentionally submitted for inclusion in the Work+ by You to the Licensor shall be under the terms and conditions of+ this License, without any additional terms or conditions.+ Notwithstanding the above, nothing herein shall supersede or modify+ the terms of any separate license agreement you may have executed+ with Licensor regarding such Contributions.++ 6. Trademarks. This License does not grant permission to use the trade+ names, trademarks, service marks, or product names of the Licensor,+ except as required for reasonable and customary use in describing the+ origin of the Work and reproducing the content of the NOTICE file.++ 7. Disclaimer of Warranty. Unless required by applicable law or+ agreed to in writing, Licensor provides the Work (and each+ Contributor provides its Contributions) on an "AS IS" BASIS,+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or+ implied, including, without limitation, any warranties or conditions+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A+ PARTICULAR PURPOSE. You are solely responsible for determining the+ appropriateness of using or redistributing the Work and assume any+ risks associated with Your exercise of permissions under this License.++ 8. Limitation of Liability. In no event and under no legal theory,+ whether in tort (including negligence), contract, or otherwise,+ unless required by applicable law (such as deliberate and grossly+ negligent acts) or agreed to in writing, shall any Contributor be+ liable to You for damages, including any direct, indirect, special,+ incidental, or consequential damages of any character arising as a+ result of this License or out of the use or inability to use the+ Work (including but not limited to damages for loss of goodwill,+ work stoppage, computer failure or malfunction, or any and all+ other commercial damages or losses), even if such Contributor+ has been advised of the possibility of such damages.++ 9. Accepting Warranty or Additional Liability. While redistributing+ the Work or Derivative Works thereof, You may choose to offer,+ and charge a fee for, acceptance of support, warranty, indemnity,+ or other liability obligations and/or rights consistent with this+ License. However, in accepting such obligations, You may act only+ on Your own behalf and on Your sole responsibility, not on behalf+ of any other Contributor, and only if You agree to indemnify,+ defend, and hold each Contributor harmless for any liability+ incurred by, or claims asserted against, such Contributor by reason+ of your accepting any such warranty or additional liability.++ END OF TERMS AND CONDITIONS++ APPENDIX: How to apply the Apache License to your work.++ To apply the Apache License to your work, attach the following+ boilerplate notice, with the fields enclosed by brackets "[]"+ replaced with your own identifying information. (Don't include+ the brackets!) The text should be enclosed in the appropriate+ comment syntax for the file format. We also recommend that a+ file or class name and description of purpose be included on the+ same "printed page" as the copyright notice for easier+ identification within third-party archives.++ Copyright 2026 Gatewai Studio++ Licensed under the Apache License, Version 2.0 (the "License");+ you may not use this file except in compliance with the License.+ You may obtain a copy of the License at++ http://www.apache.org/licenses/LICENSE-2.0++ Unless required by applicable law or agreed to in writing, software+ distributed under the License is distributed on an "AS IS" BASIS,+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+ See the License for the specific language governing permissions and+ limitations under the License.\ No newline at end of filediff --git a/plugins/gitframes/README.md b/plugins/gitframes/README.mdnew file mode 100644index 00000000..bae20a10--- /dev/null+++ b/plugins/gitframes/README.md@@ -0,0 +1,23 @@+# Gitframes agent skills++Agent skills for [gitframes](https://github.com/gatewai-dev/gitframes), a code-first video SDK that renders compositions natively on WebGPU in Node.js. The skills teach Claude, Codex, and other coding agents how to write, render, and check gitframes compositions in your own project.++| Skill | Use it for |+| --- | --- |+| `gitframes-compose` | Compositions, layer trees, layout, animation and easing, beat grids, film structure |+| `gitframes-effects` | Post-processing effects, color grading, VFX, and on-device vision (tracking, segmentation, pose) |+| `gitframes-render` | Headless rendering, frame-grid inspection, pixel probes, MP4 delivery checks |++Skills load automatically when a task matches, for example *"add a film-grain pass to this scene"* or *"render a frame grid of intro.ts"*.++## How it works++This plugin contains only skills: Markdown instructions for your agent. It bundles no executables, MCP servers, hooks, or package launchers. The engine itself is the [`gitframes`](https://www.npmjs.com/package/gitframes) npm package, which the skills tell your agent to add to your project (`npm install gitframes`, Node.js 22 or later).++## Data and privacy++The plugin sends no data anywhere. When code that uses gitframes' on-device vision features runs, the SDK downloads pinned, Apache-2.0 model weights from Hugging Face the first time each model is used and verifies them by SHA-256. Nothing else leaves your machine.++## License++Apache-2.0. See [LICENSE](LICENSE).diff --git a/plugins/gitframes/assets/logo.png b/plugins/gitframes/assets/logo.pngnew file mode 100644index 00000000..cbb506c8Binary files /dev/null and b/plugins/gitframes/assets/logo.png differdiff --git a/plugin.json b/plugins/gitframes/plugin.jsonsimilarity index 95%rename from plugin.jsonrename to plugins/gitframes/plugin.jsonindex 40159261..a92f142f 100644--- a/plugin.json+++ b/plugins/gitframes/plugin.json@@ -1,7 +1,7 @@{"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json","name": "gitframes",- "version": "0.1.0",+ "version": "1.3.1","description": "Author, render and verify video compositions with the gitframes WebGPU SDK.","author": {"name": "Gitframes"diff --git a/skills/gitframes-compose/SKILL.md b/plugins/gitframes/skills/gitframes-compose/SKILL.mdsimilarity index 96%rename from skills/gitframes-compose/SKILL.mdrename to plugins/gitframes/skills/gitframes-compose/SKILL.mdindex fb936c30..b9e7c94e 100644--- a/skills/gitframes-compose/SKILL.md+++ b/plugins/gitframes/skills/gitframes-compose/SKILL.md@@ -5,6 +5,9 @@ description: Design, structure, and animate code-first video compositions using# gitframes-compose+## Setup+These skills drive the [`gitframes`](https://www.npmjs.com/package/gitframes) npm package. If the project doesn't depend on it yet, add it with the project's package manager (`npm install gitframes`, or the `pnpm`/`yarn`/`bun` equivalent) and import from `"gitframes"`. It needs Node.js 22 or later and a WebGPU-capable GPU (Metal or Vulkan).+## Overview`gitframes` is a code-first, deterministic video composition SDK executing natively on WebGPU (Dawn) in Node.js. It replaces browser-based rendering (Puppeteer/Chromium) with high-performance GPU pipelines, Yoga flexbox layout, Slug vector typography, 3D camera transforms, and reactive audio/signal drivers.diff --git a/skills/gitframes-effects/SKILL.md b/plugins/gitframes/skills/gitframes-effects/SKILL.mdsimilarity index 96%rename from skills/gitframes-effects/SKILL.mdrename to plugins/gitframes/skills/gitframes-effects/SKILL.mdindex f7cd08bb..e5bbcabf 100644--- a/skills/gitframes-effects/SKILL.md+++ b/plugins/gitframes/skills/gitframes-effects/SKILL.md@@ -5,6 +5,9 @@ description: Apply, configure, and modulate WebGPU post-processing shaders, cine# gitframes-effects+## Setup+These skills drive the [`gitframes`](https://www.npmjs.com/package/gitframes) npm package. If the project doesn't depend on it yet, add it with the project's package manager (`npm install gitframes`, or the `pnpm`/`yarn`/`bun` equivalent) and import from `"gitframes"`. It needs Node.js 22 or later and a WebGPU-capable GPU (Metal or Vulkan).+## Overview`gitframes` features a native WebGPU shader execution pipeline for 2D VFX, tonal grading, cinematic lens simulation, spatial relighting, and real-time neural vision conditioning.@@ -172,7 +175,7 @@ Measured per 1280–2048 px frame on CPU (`onnxruntime-node`):| Cutout is the wrong object | Set `classes: ["person"]` (or the class you want) || Faint halo around the cutout on dark backgrounds | Lower `featherRadius`, or raise `maskThreshold` (e.g. `0.6`) || Renders offline / in CI | Pre-download with `runner.preload([...])` into `$GITFRAMES_MODELS_DIR`, or point `GITFRAMES_MODELS_BASE_URL` at a mirror |-| Check the models themselves | `pnpm --filter @gitframes/vision test:models` (downloads ~380 MB once) |+| Check the models themselves | `await runner.preload([...])` on a fresh models directory; it downloads each model and verifies its SHA-256 (about 380 MB for all of them) |### 1. Subject Sandwich ("Text Behind Subject")Cuts out the foreground subject from footage and sandwiches typography or graphics directly behind them:diff --git a/skills/gitframes-effects/references/effects-catalog.md b/plugins/gitframes/skills/gitframes-effects/references/effects-catalog.mdsimilarity index 100%rename from skills/gitframes-effects/references/effects-catalog.mdrename to plugins/gitframes/skills/gitframes-effects/references/effects-catalog.mddiff --git a/skills/gitframes-render/SKILL.md b/plugins/gitframes/skills/gitframes-render/SKILL.mdsimilarity index 93%rename from skills/gitframes-render/SKILL.mdrename to plugins/gitframes/skills/gitframes-render/SKILL.mdindex dde67739..aed3ac65 100644--- a/skills/gitframes-render/SKILL.md+++ b/plugins/gitframes/skills/gitframes-render/SKILL.md@@ -5,6 +5,9 @@ description: Render, inspect, test, and export high-performance WebGPU video and# gitframes-render+## Setup+These skills drive the [`gitframes`](https://www.npmjs.com/package/gitframes) npm package. If the project doesn't depend on it yet, add it with the project's package manager (`npm install gitframes`, or the `pnpm`/`yarn`/`bun` equivalent) and import from `"gitframes"`. It needs Node.js 22 or later and a WebGPU-capable GPU (Metal or Vulkan).+## Overview`gitframes` renders headlessly in Node.js on top of native WebGPU (Dawn) and mediabunny WebCodecs hardware encoders. It does not run a browser, Puppeteer, or Chromium.@@ -20,7 +23,7 @@ Always proceed through the ladder in order. Catching a layout or timing bug at sBefore touching the GPU, verify TypeScript types and parse the composition against the strict runtime schema:```typescript-import { CompositorProgramSchema } from "@gitframes/compositions/program";+import { CompositorProgramSchema } from "gitframes";// 1. Compile specconst spec = comp.toSpec();@@ -33,9 +36,9 @@ if (!parsed.success) {}```-Run package typechecking:+Typecheck the project:```bash-pnpm --filter <example-or-package> typecheck+npx tsc --noEmit -p .```---@@ -171,8 +174,6 @@ if (mode === "frames") {process.exit(0);```-To run against the engine's TypeScript source instead of built `dist` (while changing the engine itself), give tsx a `tsconfig.dev.json` that extends the project's tsconfig and adds `"../../packages/**/*"` and `"../../nodes/**/*"` to `include` (tsx only applies compiler options, such as the decorators `server-utils` needs, to included files), then run `tsx --tsconfig tsconfig.dev.json --conditions=development src/render.ts`. `examples/22_gitframes_launch` has it as `pnpm render:src`.-CLI Usage:```bash# Render specific keyframes for instant review:diff --git a/scripts/generate-effects.mts b/scripts/generate-effects.mtsindex eee96472..229b392d 100644--- a/scripts/generate-effects.mts+++ b/scripts/generate-effects.mts@@ -11,7 +11,7 @@// Output (never edit by hand):// packages/gitframes/src/effects/generated/{classes,meta,registry,index}.ts// packages/gitframes/src/effects/generated/catalog.json-// skills/gitframes-effects/references/effects-catalog.md (via sync-effects-catalog.mjs)+// plugins/gitframes/skills/gitframes-effects/references/effects-catalog.md (via sync-effects-catalog.mjs)//// A node takes part once its package.json names a `schema`. Nodes without one// are not migrated yet and keep their hand-written class in effects/classes.ts.diff --git a/scripts/sync-effects-catalog.mjs b/scripts/sync-effects-catalog.mjsindex faa1e8c5..e92fdc92 100644--- a/scripts/sync-effects-catalog.mjs+++ b/scripts/sync-effects-catalog.mjs@@ -35,6 +35,8 @@ const GENERATED_CATALOG = join(EFFECTS_DIR, "generated", "catalog.json");const NODES_DIR = join(repoRoot, "nodes");const OUTPUT = join(repoRoot,+ "plugins",+ "gitframes","skills","gitframes-effects","references",diff --git a/scripts/sync-plugin-version.mjs b/scripts/sync-plugin-version.mjsnew file mode 100644index 00000000..b600595a--- /dev/null+++ b/scripts/sync-plugin-version.mjs@@ -0,0 +1,36 @@+#!/usr/bin/env node+// Keeps the agent plugin version in lockstep with the released `gitframes` package.+//+// Runs after `changeset version` (see `version:packages`), so every release bumps the+// version in all three plugin manifests. Clients compare that version to decide when+// to update, so a stale one leaves users on old skills.+//+// Dependency-free on purpose, like validate-agent-plugin.mjs.+import { readFileSync, writeFileSync } from "node:fs";+import { dirname, join, resolve } from "node:path";+import { fileURLToPath } from "node:url";++const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");+const MANIFESTS = [+ "plugins/gitframes/plugin.json",+ "plugins/gitframes/.claude-plugin/plugin.json",+ "plugins/gitframes/.codex-plugin/plugin.json",+];++const { version } = JSON.parse(+ readFileSync(join(repoRoot, "packages/gitframes/package.json"), "utf8"),+);++for (const manifest of MANIFESTS) {+ const path = join(repoRoot, manifest);+ const source = readFileSync(path, "utf8");+ // Replace the value in place so the file's formatting and key order survive.+ const updated = source.replace(+ /("version"\s*:\s*)"[^"]*"/,+ `$1${JSON.stringify(version)}`,+ );+ if (updated === source && JSON.parse(source).version !== version)+ throw new Error(`${manifest}: no "version" field to update`);+ writeFileSync(path, updated);+ console.log(`${manifest} → ${version}`);+}diff --git a/scripts/validate-agent-plugin.mjs b/scripts/validate-agent-plugin.mjsindex 1b4b0a47..cc0d0005 100644--- a/scripts/validate-agent-plugin.mjs+++ b/scripts/validate-agent-plugin.mjs@@ -1,11 +1,13 @@#!/usr/bin/env node// Structural validator for the gitframes agent plugin.//-// The repository root *is* the plugin root, so every client discovers the same skills:+// The plugin lives in plugins/gitframes/ so installs ship only the skills, not the engine+// (users get the engine from npm). Every client discovers the same skills from there:// plugin.json portable Agent Plugins 1.0 manifest (closed field set)// .claude-plugin/plugin.json Claude Code manifest// .codex-plugin/plugin.json OpenAI Codex manifest (declares skills: "./skills/")// skills/<name>/SKILL.md the skills themselves+// README.md, LICENSE required by Anthropic's plugin directory//// Enforces the rules we depend on from:// - Agent Plugins 1.0.0 (portable manifest, fixed component locations, path containment)@@ -26,7 +28,7 @@ import { dirname, join, relative, resolve, sep } from "node:path";import { fileURLToPath } from "node:url";const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");-const PLUGIN_DIR = repoRoot;+const PLUGIN_DIR = join(repoRoot, "plugins", "gitframes");const PLUGIN_NAME = "gitframes";const MARKETPLACE_NAME = "gitframes-plugins";const AGENT_PLUGINS_SCHEMA =@@ -157,9 +159,19 @@ function checkManifests() {ok(`version pinned consistently at ${portable.version} across all three manifests`,);- // NOTE: no lockfile check here. The plugin root is the repository root, so the monorepo's- // own pnpm-lock.yaml is expected; the "plugin must not ship a lockfile" rule only applies- // to a standalone plugin directory.+ if (claude.icon && !existsSync(join(PLUGIN_DIR, claude.icon)))+ fail(`.claude-plugin/plugin.json: icon ${claude.icon} does not exist`);+ for (const file of ["README.md", "LICENSE"]) {+ if (!existsSync(join(PLUGIN_DIR, file)))+ fail(+ `${rel(join(PLUGIN_DIR, file))} is missing (the plugin directory requires it)`,+ );+ }+ // The plugin ships to users as-is: no lockfile or package.json, or installs run npm.+ for (const file of ["package.json", "package-lock.json", "pnpm-lock.yaml"]) {+ if (existsSync(join(PLUGIN_DIR, file)))+ fail(`${rel(join(PLUGIN_DIR, file))} must not ship with the plugin`);+ }}function checkSkills() {@@ -248,10 +260,8 @@ function checkMarketplace(file, kind) {);continue;}- // "./" resolves to the repo root, which is a legal marketplace-root source (the plugin- // root *is* the repo root); anything deeper must stay inside the repo.const dir = resolve(repoRoot, source);- if (dir !== repoRoot && !insideRepo(source)) {+ if (!insideRepo(source)) {fail(`${rel(file)}: entry "${entry.name}" escapes the repo root`);continue;}@@ -270,7 +280,7 @@ function checkMarketplace(file, kind) {`${rel(file)}: entry "${entry.name}" is not a ${kind} plugin (${rel(manifest)} missing)`,);for (const skillPath of entry.skills ?? []) {- if (!existsSync(resolve(repoRoot, skillPath)))+ if (!existsSync(resolve(dir, skillPath)))fail(`${rel(file)}: entry "${entry.name}" lists missing skill ${skillPath}`,);@@ -311,14 +321,14 @@ function checkSymlinks() {continue;}const target = realpathSync(path);- const expected = join(repoRoot, "skills", name);+ const expected = join(PLUGIN_DIR, "skills", name);if (!statSync(target).isDirectory())fail(`${link}: must point at a directory`);else if (!existsSync(join(target, "SKILL.md")))fail(`${link}: target has no SKILL.md`);else if (target !== expected)- fail(`${link}: must point at skills/${name} (found ${rel(target)})`);- else ok(`${link} -> skills/${name}`);+ fail(`${link}: must point at ${rel(expected)} (found ${rel(target)})`);+ else ok(`${link} -> ${rel(expected)}`);}}}