developing-leaf

name	developing-leaf
description	Develops Leaf from the current checkout by previewing examples, comparing runtimes, refreshing catalog stills, and testing page changes in the browser.

Develop Leaf from this checkout

Resolve the repository root three directories above this SKILL.md, then resolve <root>/bin/leaf to an absolute path. Run that launcher with --version and continue only when it prints the same repository root. Use the absolute launcher throughout; a bare leaf command may resolve to the installed plugin instead.

Use the visible-change handoff in <root>/CLAUDE.md to choose a workflow. When a visual or content artifact would help the developer judge the work, put a draft in front of them during exploration or at handoff rather than relying on a description alone. Preview a shipped example when the request names one or that handoff requires interactive proof. Otherwise author or revise a page.

Before presenting a served page or visible runtime change as finished, inspect the exact served URL. When the subject is Leaf's own interface, the demonstrated surface must come from its owning runtime and theme through a shipped example or fixture; page-local HTML and CSS may frame it, but must not imitate it. Call an unimplemented imitation a sketch, not a preview. Confirm the expected content, review the changed surface at a representative viewport, and check the browser console. Navigate to the semantic block that owns the changed surface and hand off the exact URL including its fragment. A titled section uses the section's stable id, so its eyebrow and heading arrive together. Add an id to the tight semantic container when it has none. Keep the process alive.

Preview a shipped example

From the repository root, start scripts/preview.py <example> in a long-running command or terminal session. Keep it alive and retain the exact served URL. The script watches source and runtime edits and preserves feedback at .tmp/previews/<example>. Repeating the command reuses that preview; use --slot <name> for another copy. A refused update appears in the terminal or the background log named at startup. Fix the input and the watcher retries.

Browser automation runs scripts/preview.py <example> --automation in a long-running process. The command uses the browser suite's temporary server: the real HTTP and event log, with no task claim or durable service. Its default page is .tmp/previews/<example>-automation; use the reader preview's distinct page when presenting a URL for feedback. An explicit slot cannot change interaction mode.

When finished with a preview, run the matching preview command with --stop (and --automation for its automation slot); it waits for the watcher and server to stop. Ctrl-C stops a foreground preview. A slot refuses a different source or seeded history so it keeps the existing page and feedback. Use --reset to discard the selected slot and rebuild it from the current fixture.

In Codex

1. Call mcp__codex_app__open_in_codex with the destination's fragment URL as a browser target and placement: "right".
2. Run <root>/bin/leaf codex start <root>/.tmp/previews/<example> so Leaf comments return to the current task.
3. Tell the user to select page text or use Leaf's comment affordance for a Leaf thread. Codex Annotation mode creates visual comments that the user sends with their next chat message. Use the Codex review pane when feedback belongs to a source line.

Refresh the public catalog stills

When a change adds or removes a worked example, or changes its first viewport, run wt refresh-previews from the repository root on macOS. Run wt setup first in a new checkout. If Worktrunk requests approval for the project commands, ask the user to run wt config approvals add. The refresh command captures every worked example, validates the rebuilt site, pushes the complete JPEG set to max-sixty/leaf-assets, and updates example-previews.json and the catalog links in this checkout. Because it pushes the asset repository immediately, run it only when the user has authorized that publication. The generator checks the required Charter and San Francisco fonts and fails rather than publishing images rendered with fallback fonts.

Compare runtime versions

Choose one authored source and serve it through two named preview slots:

scripts/preview.py --source <source.html> --runtime <baseline-root> \
  --slot baseline --background
scripts/preview.py --source <source.html> --runtime <candidate-root> \
  --slot candidate --background

Each command verifies the checkout launcher, prepares or resumes its independent page, watches that runtime and source, and prints its exact URL. Exercise the same journey and viewport at both URLs, check both browser consoles, then navigate both to the same authored destination id. Hand off the labeled URL pair and the action that reveals the difference; in Codex, open those exact fragment URLs as browser targets.

Author or revise a page

Read <root>/skills/leaf/SKILL.md completely and follow its authoring, validation, handoff, and conversation-loop routes. Use the checkout launcher's absolute path for every command written there as leaf, and resolve its references from <root>/skills/leaf/.

page init vendors the checkout's runtime, theme, registry, widgets, and assets into the page. For an existing page that must exercise the current checkout, read <root>/skills/leaf/references/serving-pages.md and re-vendor it with the checkout launcher. A served page follows that reference's stop, init, start sequence. Fix or report a compatibility refusal without falling back to the installed plugin.