takomi 2.1.40 → 2.1.41

package/assets/.agent/skills/remotion-real-ui-video/references/anti-patterns.md

@@ -0,0 +1,114 @@
+# Anti-Patterns
+
+Use this reference before and during review. If any anti-pattern appears, stop and correct it before calling the work complete.
+
+## Anti-pattern 1: Pretty fake app screen
+
+### Symptom
+
+The composition creates custom JSX that resembles an existing app screen:
+
+- handmade dashboard
+- handmade form
+- handmade table/grid
+- handmade score sheet
+- handmade sidebar/header
+- handmade report card
+
+### Why it is wrong
+
+The video may look polished, but it no longer proves or showcases the real product UI. Future UI changes will not carry into the video, and the agent has violated the real-UI workflow.
+
+### Correct response
+
+Find the actual app component and import/extract it. Replace only data/runtime boundaries.
+
+## Anti-pattern 2: Existing component ignored
+
+### Symptom
+
+The codebase has components like:
+
+```txt
+SelectionBar
+RosterGrid
+SaveActionBar
+ReportPreview
+WorkspaceShell
+SettingsForm
+BillingTable
+```
+
+But the Remotion composition builds similar JSX itself.
+
+### Correct response
+
+Use the existing components. If they are not exportable, export them or extract a presentational view.
+
+## Anti-pattern 3: Semantic targets without semantic measurement
+
+### Symptom
+
+The agent adds `data-video-target`, but cursor/touch positions still come from hardcoded coordinates.
+
+### Correct response
+
+Measure the target with `getBoundingClientRect()`, normalize to composition coordinates, and use fallback coordinates only when measurement is unavailable.
+
+## Anti-pattern 4: Raw bounding rect coordinates
+
+### Symptom
+
+The code uses:
+
+```ts
+x: targetRect.left - rootRect.left
+```
+
+without compensating for Remotion Studio scaling.
+
+### Correct response
+
+Use composition width/height from `useVideoConfig()`:
+
+```ts
+const scaleX = rootRect.width / compositionWidth;
+const scaleY = rootRect.height / compositionHeight;
+
+x = (targetRect.left - rootRect.left) / scaleX;
+y = (targetRect.top - rootRect.top) / scaleY;
+```
+
+## Anti-pattern 5: CSS transitions on frame-driven motion
+
+### Symptom
+
+Frame-driven scroll/camera transforms use CSS `transition`.
+
+### Why it is wrong
+
+The browser interpolates while Remotion samples exact frames, causing jitter or stutter.
+
+### Correct response
+
+Use deterministic frame values only, e.g. `translate3d(...)`, and no CSS transition.
+
+## Anti-pattern 6: Registered but not renderable
+
+### Symptom
+
+A composition is registered, but there are no scripts/commands for stills, debug stills, or final video.
+
+### Correct response
+
+Add or document render commands before calling the work done.
+
+## Anti-pattern 7: Unreviewed production edits
+
+### Symptom
+
+Shared/production components are changed to satisfy Remotion, but no one checks whether live behavior changed.
+
+### Correct response
+
+Review every production edit. Prefer additive props, `data-video-target`, exports, or presentational extraction. Avoid changing live auth/data/routing/import behavior unless deliberately required.

package/assets/.agent/skills/remotion-real-ui-video/references/completion-checklist.md

@@ -0,0 +1,75 @@
+# Completion Checklist
+
+Use this checklist before saying a Remotion real-UI video task is complete.
+
+## Pre-implementation report
+
+- [ ] Listed real UI source files for every app-screen scene.
+- [ ] Listed real components imported or extracted.
+- [ ] Listed runtime/data/provider boundaries replaced with demo/local equivalents.
+- [ ] Identified which scenes are marketing overlays only.
+- [ ] Asked the user before creating any video-only mockup of an existing app screen.
+
+## Real UI compliance
+
+For each app-screen scene:
+
+- [ ] Scene imports/extracts real app UI components.
+- [ ] Scene does not hand-build a lookalike dashboard/form/table/screen.
+- [ ] Demo data enters through props/providers/boundaries, not by rewriting visual JSX.
+- [ ] Any production/shared component changes are additive and low-risk.
+
+## Timeline and interaction compliance
+
+- [ ] Interactions are centralized in a timeline/action object.
+- [ ] Every action has `targetId`, fallback coordinates, `downFrame`, `upFrame`, and `commitFrame`.
+- [ ] UI/route/data changes happen at `commitFrame`, after click/tap release.
+- [ ] Desktop uses cursor indicators; mobile uses touch indicators.
+- [ ] Mobile scroll is frame-driven and deterministic, with no CSS transitions.
+
+## Target measurement compliance
+
+- [ ] Click/tap targets use `data-video-target`.
+- [ ] DOM measurements use `getBoundingClientRect()`.
+- [ ] Measurements are normalized from viewport/Studio-scaled pixels into composition coordinates.
+- [ ] Debug overlays use the same normalized coordinate space as the cursor/touch indicator.
+- [ ] Fallback hardcoded coordinates are used only if measurement is unavailable.
+
+## Render and artifact compliance
+
+- [ ] Final composition canvas uses full HD by default: 1920×1080 for landscape or 1080×1920 for portrait/mobile, unless the user explicitly requested a smaller/different size.
+- [ ] Typechecked every touched package.
+- [ ] Rendered stills at key scene/action frames.
+- [ ] Rendered at least one debug-overlay still per composition.
+- [ ] Added or documented still/debug/final video render commands.
+- [ ] Rendered final video artifact unless user requested stills only.
+- [ ] Compared output scene-by-scene against the user's script.
+- [ ] Checked that UI is not cramped, clipped, or too small on the chosen canvas.
+
+## Required final report
+
+When reporting completion, include:
+
+```txt
+Real UI reused:
+- Scene <n>: <component> from <path>
+
+Demo boundaries:
+- <boundary>: <demo/local replacement>
+
+Verification:
+- typecheck command(s)
+- still/debug artifact(s)
+- final video artifact
+
+Known gaps:
+- <none or explicit caveat>
+```
+
+## Golden task mental test
+
+Before implementation, ask:
+
+> If the product team changes the real app screen tomorrow, would this video scene naturally inherit that change?
+
+If the answer is no because the screen was recreated in Remotion, the implementation has failed this skill unless the user explicitly requested a mockup/redesign.

package/assets/.agent/skills/remotion-real-ui-video/references/real-ui-bridge-example.md

@@ -0,0 +1,93 @@
+# Real UI Bridge Reference
+
+Use this reference when implementing a Remotion composition for an existing app screen.
+
+## Required pattern
+
+```txt
+Existing app route/page
+  -> live container/hooks/providers
+  -> RealFeatureView props
+
+Remotion composition
+  -> imports RealFeatureView
+  -> supplies deterministic demo props
+  -> drives route/state from timeline commit frames
+  -> overlays cursor/touch/highlights around the real UI
+```
+
+## Good example shape
+
+```tsx
+// app/admin/scores/page.tsx
+export default function ScoresPage() {
+  const session = useLiveSession();
+  const data = useScoresQuery(session.schoolId);
+  return <ScoresWorkspaceView data={data} onSave={saveScores} />;
+}
+
+// app/admin/scores/ScoresWorkspaceView.tsx
+export function ScoresWorkspaceView({ data, onSave }: Props) {
+  return (
+    <WorkspaceShell>
+      <ScoreSelector value={data.selection} />
+      <ScoreGrid rows={data.rows} onSave={onSave} />
+      <PreviewAction />
+    </WorkspaceShell>
+  );
+}
+
+// remotion/compositions/ScoresDemo.tsx
+export function ScoresDemo() {
+  const frame = useCurrentFrame();
+  const scene = getScene(frame);
+  return (
+    <AbsoluteFill data-video-coordinate-root>
+      <ScoresWorkspaceView
+        data={getDemoScoresData(scene)}
+        onSave={() => undefined}
+      />
+      <TimelineCursor />
+    </AbsoluteFill>
+  );
+}
+```
+
+## Bad example shape
+
+```tsx
+// remotion/compositions/ScoresDemo.tsx
+// BAD: This redraws the app screen from scratch even though real components exist.
+function FakeScoreGrid() {
+  return <table>{/* handmade lookalike rows */}</table>;
+}
+```
+
+This is unacceptable unless the user explicitly approved a video-only mockup/redesign after being told real UI reuse is not being attempted.
+
+## Refactor rule
+
+If the real screen is coupled to live hooks/auth/API calls, do not clone the JSX. Extract a presentational view:
+
+```txt
+Before:
+ScoresPage contains hooks + full JSX
+
+After:
+ScoresPage contains hooks and passes props
+ScoresWorkspaceView contains the existing JSX
+Remotion imports ScoresWorkspaceView
+```
+
+## Marketing overlay rule
+
+New Remotion-only JSX is allowed for:
+
+- hook cards
+- captions
+- CTA/end cards
+- spotlights/highlights
+- cursor/touch indicators
+- camera masks/backgrounds
+
+It is not allowed for replacing existing app screens.