Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions sdk/guides/craft/motion.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,8 @@ Read the files a task needs with `raea guide motion/NAME`, one or two at a time,
| meshes, lights, cameras, modelled solids | `motion/3d`, then `bevy` (the 3D library: lights, materials, models, effects, 3D games) |
| input, rules, scores, sound on game events | `motion/games` |
| rendering stills or the video, and checking them | `motion/rendering` |
| the shapes, lengths and platforms it ships to, the files, posting deliverables | `motion/delivery` |
| an app's interface (its own window, not a composition): every state, built and checked by walking it | `motion/interface` |

## The core rules

Expand Down
107 changes: 107 additions & 0 deletions sdk/guides/craft/motion/delivery.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,107 @@
# Delivery: shapes, platforms, the files and handing them over

## What to do

- Start from what's asked for. The brief's deliverables say the pieces; the workspace's delivery controller, when
there is one (`raea controller ls`, or `controllers_read` in the app), says the shapes, lengths, platforms, caption
rule and loudness for every piece. Work to it. When neither says where a piece goes, ask once with your best guess,
or write the guess and add it to the brief's `assumed`.
- Make each shape as its own composition from the same scenes (`motion/compositions`), laid out for that shape: a
vertical cut puts its type and faces where a vertical frame has room, it doesn't crop the wide one. Name them by
shape (`launch-9x16`, `launch-1x1`, `launch-16x9`).
- Make the shape a platform is made for first: the first shape listed for it in the skill's reference/platforms.md
(9:16 for TikTok, Reels and Shorts). A network that shows several shapes takes the one the brief favours.
- Fit the length to where it goes: inside the platform's limits, and near the length its feed favours when the brief
doesn't set one. A cutdown (6 s, 15 s, 30 s) is its own edit with its own hook, not the long one stopped early.
- Keep text and faces out of the platform's UI zones for that shape (reference/platforms.md; `motion/placement` for
how), then check the export against the platform:
`raea check out/launch-9x16.mp4 --manifest out/render.json --shape 9:16 --platform tiktok`.
- Captions: burn them in for feeds that play without sound, unless the delivery controller says captions off; then
burn none, and leave the words file beside the export for the platform's own captions.
- Sound to -14 LUFS integrated with true peak at or below -1 dBTP: one `<Mix lufs={-14} ceiling={-1.5} />` per
composition does it (`motion/sound`). A spec that names another number wins.
- Render the export at `--quality master`, named in lowercase letters, digits and hyphens, with its shape and length:
`spring-launch-9x16-15s.mp4`. Each version is a new file beside the last, never written over it.
- In the raea app, post each deliverable with `feed_post` and `export: true`, tagged with the same keys across the
project (`platform:tiktok`, `aspect:9x16`, `cut:15s`, `market:uk`): they become the project's Table, which is how
the person sees what's done and what's missing. `item_tags` tags one that's already posted. Headless, list the
files with their shape, length and platform for the person.
- Publishing is the person's. The app's Publish view sends a post to a network, now or at a time, after checking it
against that network's guidelines; nothing goes out until they press Publish or Schedule. Have the file, its tags
and, when asked, a caption within the network's limit ready for them.
- When the deliverable isn't a video: a game as its own program is `raea export-game` (`games`), an app is
`raea app bundle` signed with the person's own identity (`apps`), and a live composition for another raea is
`raea bundle --composition-bundle`.

## Why

Every network shows a video inside its own interface, and a frame made for one shape loses its type, its faces or
its hook in another. The numbers that decide this (shapes, lengths, file sizes, caption limits, where the buttons sit)
are the app's own publishing guidelines, generated into reference/platforms.md, so a delivery made to them is one
Publish accepts without a fix. Tags with the same keys across a project are what make the Table a delivery list
rather than a pile of files.

## Common mistakes

- A 16:9 master cropped to 9:16 at the end. The type runs off the sides and the face sits under the buttons. Lay the
vertical out as its own composition.
- Text in the bottom quarter of a vertical frame, where every short-video network puts its caption and buttons.
- A 15 s cutdown that is the first 15 seconds of the long cut, with no ending.
- Captions burned in on a piece whose delivery controller says captions off, or burned in twice: once by the piece,
once by the platform's auto-captions the person turned on.
- `final-v2-FINAL.mp4`, `Launch Video (1).mp4`, or a new render written over the version the person last saw.
- Tags that change keys between items (`tiktok`, `platform:TikTok`, `network:tiktok`): the Table makes three columns.
- Posting to a network, or asking the person for their password to. Publishing is the person's, from Publish.

## Example: one piece in the three shapes it ships in

```tsx
import { AbsoluteFill, Composition, Sequence, registerRoot, useVideoConfig } from "raea";
import { css } from "./styles.gen";

const fps = 30;
const s = (sec: number) => Math.round(sec * fps);

/** The hook and the end card, laid out from the frame's own shape. */
export default function Launch({ cut }: { cut: number }) {
const { width, height } = useVideoConfig();
const tall = height > width;
const u = width / 1080;
return (
<AbsoluteFill style={{ background: "var(--brand-background)" }}>
<style>{css}</style>
<Sequence from={0} durationInFrames={s(cut) - s(2)}>
{/* a vertical frame keeps its line in the upper middle, clear of the caption and buttons below */}
<AbsoluteFill style={{ justifyContent: tall ? "flex-start" : "center", alignItems: "center", paddingTop: tall ? height * 0.3 : 0 }}>
<div style={{ fontFamily: "var(--brand-font-heading)", fontWeight: 800, color: "var(--brand-text)", fontSize: Math.round((tall ? 110 : 90) * u), textAlign: "center", maxWidth: width * 0.8 }}>
Sun in a can.
</div>
</AbsoluteFill>
</Sequence>
<Sequence from={s(cut) - s(2)} durationInFrames={s(2)}>
<AbsoluteFill style={{ justifyContent: "center", alignItems: "center", color: "var(--brand-text)", fontSize: Math.round(72 * u) }}>
Try Sunmelt
</AbsoluteFill>
</Sequence>
</AbsoluteFill>
);
}

function Root() {
return (
<>
<Composition id="launch-9x16-15s" component={Launch} width={1080} height={1920} fps={fps} durationInFrames={s(15)} defaultProps={{ cut: 15 }} />
<Composition id="launch-1x1-15s" component={Launch} width={1080} height={1080} fps={fps} durationInFrames={s(15)} defaultProps={{ cut: 15 }} />
<Composition id="launch-16x9-30s" component={Launch} width={1920} height={1080} fps={fps} durationInFrames={s(30)} defaultProps={{ cut: 30 }} />
</>
);
}
registerRoot(Root);
```

Then each one rendered, checked against where it goes and posted as a deliverable:

```sh
raea render launch.tsx --composition launch-9x16-15s --quality master -o out/launch-9x16-15s.mp4 --manifest out/9x16.json
raea check out/launch-9x16-15s.mp4 --manifest out/9x16.json --shape 9:16 --platform tiktok
```
113 changes: 113 additions & 0 deletions sdk/guides/craft/motion/interface.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,113 @@
# Interfaces: an app on @raea/ui, built state by state and checked by walking it

`modes/tool` says what an interface has to do for the person using it; this file is how to build one in raea and
show that it does. The verbs and the two targets are in the raea skill's "Apps: web or native".

## What to do

- Write down the task before the screen: who opens it, what they came to do, and the two or three steps that do it.
The first screen opens on that task, with its next step in plain view.
- Pick the target from what the app needs, in its own file: `export const app = { target: "web", title, size,
minSize }`. Web unless it is small, motion-heavy, has no 3D and passes the check on native. Give it a `size` it
opens at and a `minSize` it never goes under, and lay it out to work across that range (flex, `md:` and up).
- Build every state as real UI the person can reach: empty (an invitation to start, with the action that starts),
one item, many, a very long name, loading, an error that says what happened and what to do, done. Each one is a
branch in the component, not a picture.
- Give the parts a check names `data-testid`, and give everything the person acts on a role and a label: a button is a
`<button>` with words in it; something clickable that isn't one gets `role`, `tabIndex={0}` and `aria-label`.
Keyboard reaches every action in reading order; Enter and Escape do what they do everywhere.
- Style with Tailwind classes or the brand's `--brand-*` variables (`motion/brand`), one accent for what can be acted
on, `dark:` for the system's appearance. Real content: real names, real lengths, real numbers.
- Write `steps` that walk the task the way the person would, through every state, and run the check on each target
the app should run on:
`raea app check app.tsx --png out/` (and `--target native` too, when native is meant). Read every PNG and
tree.json: each state looks designed, nothing is cut off, every control has its role and label.
- A note on an app is a move like any other (`adapt` for sizes, `clarify` for words, `harden` for the states that
break, `optimize` for speed): read the move before changing the file.

## Why

The check only shows what the steps reach. An app checked at its first screen with no steps passes while its empty
list, its error and its long names are undesigned, and those are where people decide it's broken. tree.json is what a
screen reader and an agent driving the app see, so a control missing its role or label there is missing for them too.

## Common mistakes

- A check with no steps: one PNG of the first screen, and every other state unseen.
- An error that stays up after the person has fixed it: clear it as soon as they act.
- An empty state that is a blank area, or the words "No items" with nothing to do next.
- A `<div onClick>` for a button: no role, no label, not reachable by Tab.
- Placeholder content (Lorem ipsum, "Item 1", "John Doe") that hides how real lengths break the layout.
- Grid on the native target, or a prop native doesn't map: the check lists it in unmapped.json. Change it, or keep the
app on web.
- A layout that only works at the size it opens at; resize to `minSize` in the steps' window or check with `--size`.

## Example: a list app whose steps walk every state

```tsx
import { useState } from "react";

export const app = { target: "web", title: "Shots", size: [420, 560], minSize: [340, 420] };

// the person's path: an empty list, a shot added, a long name, a bad name refused, one removed
export const steps = [
{ type: "Wide of the cubicle, morning light through the blinds onto the desk", into: "name" },
{ press: "add" },
{ type: "Close on the can", into: "name" },
{ press: "add" },
{ press: "add" },
{ press: "remove-0" },
];

export default function Shots() {
const [shots, setShots] = useState<string[]>([]);
const [name, setName] = useState("");
const [error, setError] = useState("");
const add = () => {
const n = name.trim();
if (!n) return setError("Name the shot first, in a few words.");
setShots([...shots, n]);
setName("");
setError("");
};
return (
<div data-testid="page" className="flex min-h-screen flex-col gap-4 bg-zinc-50 p-5 dark:bg-zinc-950">
<h1 className="text-lg font-semibold text-zinc-900 dark:text-zinc-50">Shot list</h1>
<div className="flex flex-row gap-2">
<input
data-testid="name"
aria-label="Shot name"
value={name}
onChange={(e) => (setName((e.target as HTMLInputElement).value), setError(""))}
className="h-9 flex-1 rounded-md border border-zinc-300 bg-white px-3 text-sm text-zinc-900 dark:border-zinc-700 dark:bg-zinc-900 dark:text-zinc-50"
/>
<button data-testid="add" onClick={add} className="h-9 rounded-md bg-amber-500 px-4 text-sm font-medium text-zinc-950">
Add shot
</button>
</div>
{error && <p data-testid="error" role="alert" className="text-sm text-red-600">{error}</p>}
{shots.length === 0 ? (
<div data-testid="empty" className="flex flex-col items-start gap-1 rounded-lg border border-dashed border-zinc-300 p-4 dark:border-zinc-700">
<span className="text-sm font-medium text-zinc-800 dark:text-zinc-200">No shots yet</span>
<span className="text-sm text-zinc-500">Name the first one above: what the camera sees, in a few words.</span>
</div>
) : (
<ul data-testid="list" className="flex flex-col gap-2">
{shots.map((s, i) => (
<li key={i} className="flex flex-row items-center gap-3 rounded-lg bg-white p-3 dark:bg-zinc-900">
<span className="w-6 text-sm text-zinc-500">{i + 1}</span>
<span className="flex-1 text-sm text-zinc-900 dark:text-zinc-50">{s}</span>
<button data-testid={`remove-${i}`} aria-label={`Remove shot ${i + 1}`} onClick={() => (setShots(shots.filter((_, j) => j !== i)), setError(""))} className="text-sm text-zinc-500 hover:text-zinc-900">
Remove
</button>
</li>
))}
</ul>
)}
</div>
);
}
```

`raea app check shots.tsx --png out/` writes out/00-mount.png (the empty state) and one PNG per step: the long name
wrapping in the list, the error under the field when Add is pressed with nothing typed, the list after a removal.
33 changes: 31 additions & 2 deletions tools/skills.sh
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
# links these instead of repeating them, so a verb, a flag, a feed tool or an export changes its reference in the
# same commit.
#
# tools/skills.sh gen write skills/skills/raea/reference/{cli,feed,files,sdk,app}.md, and copy the craft guides
# tools/skills.sh gen write skills/skills/raea/reference/{cli,feed,files,sdk,app,platforms}.md, and copy the craft guides
# (sdk/guides/craft, what `raea guide` prints) into the skill (copies() below: bevy/ as 3d/,
# motion.md and motion/, and the router, floor, rubric, modes/ and verbs/ under craft/), so a
# clone of raea-skills reads whole without raea; commit them in raea-skills, then the pointer here
Expand Down Expand Up @@ -88,6 +88,34 @@ gen_cli() {
else empty end))'
}

gen_platforms() {
# the app's publishing guidelines (apps/app src/publish/specs.ts at the recorded commit; it imports nothing)
local p; p=$(mktemp -d "${TMPDIR:-/tmp}/skills-platforms.XXXXXX")
git -C "$APP" show "$APP_REV:src/publish/specs.ts" > "$p/specs.ts"
bun -e '
const { SPECS } = await import(process.argv[1] + "/specs.ts")
console.log(JSON.stringify(Object.entries(SPECS).filter(([, s]) => s.aspects.length).map(([name, s]) => ({ name, ...s }))))
' "$p" | jq -r --arg head "$HEAD_LINE" '
def secs: if . == null then "" elif . >= 3600 and . % 3600 == 0 then "\(. / 3600) h" elif . >= 60 and . % 60 == 0 then "\(. / 60) min" else "\(.) s" end;
def size: if . == null then "" elif . >= 1073741824 then "\(. / 1073741824) GB" else "\(. / 1048576) MB" end;
def pct: (. * 100 | round | tostring) + "%";
$head, "",
"# Platforms",
"",
"What each network the raea app publishes to shows and takes, from the app'"'"'s publishing guidelines (apps/app",
"src/publish/specs.ts): the Publish view checks a post against them before it goes. Shapes are w:h, the first the",
"one the network is made for. Length is the shortest and longest it takes, and the length its feed favours. The",
"safe zone is how much of a vertical frame its own buttons, caption and profile row cover on a phone, from each",
"edge: keep text and faces out of it (`raea check --platform` measures it).",
"",
"| network | shapes | length | favours | file | caption | hashtags | links in caption | safe zone (top, bottom, left, right) |",
"|---|---|---|---|---|---|---|---|---|",
(.[] | "| \(.name) | \(.aspects | join(", ")) | \(if .minDuration and .maxDuration then "\(.minDuration | secs) to \(.maxDuration | secs)" elif .maxDuration then "up to \(.maxDuration | secs)" else "" end) | \(.sweetSpot | secs) | \(.maxBytes | size) | \(.caption)\(if .graphemes then " graphemes" else " chars" end) | \(if .hashtags then ([(if .hashtags.advice then "\(.hashtags.advice[0])-\(.hashtags.advice[1]) advised" else empty end), (if .hashtags.max then "\(.hashtags.max) max" else empty end)] | join(", ")) elif .topicTags then "\(.topicTags) topic tag" else "" end) | \(if .deadLinks then "not clickable" else "" end) | \(if .safe then "\(.safe.top | pct), \(.safe.bottom | pct), \(.safe.left | pct), \(.safe.right | pct)" else "" end) |"),
"",
(.[] | select(.notes) | "- \(.name): \(.notes | join(" "))")'
rm -rf "$p"
}

gen_feed() {
# protocol.ts at the recorded commit (it imports nothing), evaluated from a scratch copy
local p; p=$(mktemp -d "${TMPDIR:-/tmp}/skills-feed.XXXXXX")
Expand Down Expand Up @@ -261,7 +289,7 @@ check() {
fi
local stale_help=0; help_stale && stale_help=1
SKILLS_OUT=$tmp/ref SKILLS_COPY_OUT=$tmp/copies R=$R SKIP_CLI=$stale_help "$0" gen-into >/dev/null || { echo "FAIL skills: tools/skills.sh gen failed"; rm -rf "$tmp"; return 1; }
for f in cli feed files sdk app; do
for f in cli feed files sdk app platforms; do
[ "$f" = cli ] && [ $stale_help = 1 ] && continue
if ! diff -q "$tmp/ref/$f.md" "$SK/raea/reference/$f.md" >/dev/null 2>&1; then
# the shared GitButler tree holds every applied lane's code, so what gen writes there isn't what main + one lane
Expand Down Expand Up @@ -414,6 +442,7 @@ case "${1:-}" in
gen_files > "$OUT/files.md"
gen_sdk > "$OUT/sdk.md"
gen_app > "$OUT/app.md"
gen_platforms > "$OUT/platforms.md"
copies | while IFS=$'\t' read -r g c; do mkdir -p "$COPY_OUT/$(dirname "$c")" && cp "$g" "$COPY_OUT/$c"; done
if [ "$1" = gen ]; then wc -l "$OUT"/*.md; fi
;;
Expand Down
Loading