hyperframes 0.7.20 → 0.7.22

package/dist/commands/layout-audit.browser.js

@@ -473,11 +473,37 @@
     return a.contains(b) || b.contains(a);
   }
 
+  function isInFlow(element) {
+    const position = getComputedStyle(element).position;
+    return position === "static" || position === "relative" || position === "sticky";
+  }
+
+  function nearestFlexGridAncestor(element) {
+    for (let parent = element.parentElement; parent; parent = parent.parentElement) {
+      const display = getComputedStyle(parent).display;
+      if (display.includes("flex") || display.includes("grid")) return parent;
+    }
+    return null;
+  }
+
+  // Two in-flow text blocks governed by the same flex/grid container are placed
+  // by the layout engine, which reserves space for each — they cannot visually
+  // collide. Any measured text-rect overlap between them is line-box / leading
+  // slop (tight stacks, number lockups, super/subscript units), not a collision.
+  // A real overlap bug needs free positioning (absolute/fixed), which keeps a
+  // different formatting context and is still flagged.
+  function isManagedFlowOverlap(a, b) {
+    if (!isInFlow(a) || !isInFlow(b)) return false;
+    const container = nearestFlexGridAncestor(a);
+    return !!container && container === nearestFlexGridAncestor(b);
+  }
+
   // Two solid text blocks whose boxes overlap by more than a fifth of the
   // smaller block read as a collision — unreadable, and invisible to the
   // overflow checks, which only compare an element against its container.
   function overlapIssue(a, b, time) {
     if (isNested(a.element, b.element)) return null;
+    if (isManagedFlowOverlap(a.element, b.element)) return null;
     const area = intersectionArea(a.rect, b.rect);
     if (area <= Math.min(rectArea(a.rect), rectArea(b.rect)) * 0.2) return null;
     return {
@@ -537,13 +563,30 @@
     return !!hit && hit !== element && !element.contains(hit) && !hit.contains(element);
   }
 
+  // During a scene-to-scene crossfade the incoming scene paints over the
+  // outgoing scene's still-visible text at >= 0.6 opacity — and `--at-transitions`
+  // samples exactly that midpoint. That overlap is the transition doing its job,
+  // not an occlusion bug. Detect it: the occluder lives in a DIFFERENT composition
+  // mount ([data-composition-id]) than the text, and at least one of the two scenes
+  // is mid-fade (effective opacity < 1). Two fully-settled scenes overlapping
+  // (both opacity 1) is NOT suppressed — that is a real layering bug.
+  function isCrossSceneTransitionOverlap(textEl, occluder) {
+    const textScene = textEl.closest("[data-composition-id]");
+    const occluderScene = occluder.closest("[data-composition-id]");
+    if (!textScene || !occluderScene || textScene === occluderScene) return false;
+    return Math.min(opacityChain(textScene), opacityChain(occluderScene)) < 0.999;
+  }
+
   // The opaque element painted over (x, y), or null when the topmost element
-  // there is related to the text or non-opaque.
+  // there is related to the text, non-opaque, or a transient crossfade overlap.
+  // fallow-ignore-next-line complexity
   function occluderAt(element, x, y) {
     if (typeof document.elementFromPoint !== "function") return null;
     const hit = document.elementFromPoint(x, y);
     if (!isForeignElement(element, hit)) return null;
-    return isOpaqueOccluder(hit) ? hit : null;
+    if (!isOpaqueOccluder(hit)) return null;
+    if (isCrossSceneTransitionOverlap(element, hit)) return null;
+    return hit;
   }
 
   // Sweep a grid across the text box (three rows, not just the mid-line, so

package/dist/skills/hyperframes-cli/SKILL.md

@@ -20,6 +20,7 @@ Everything runs through `npx hyperframes` unless project instructions specify a
    - Deliver: `npx hyperframes render --quality high --output out.mp4`
    - CI / cross-host repro: `npx hyperframes render --docker --strict --output out.mp4`
    - Cloud (long / large): `npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait` (see Lambda below)
+8. **Report feedback** — after verifying the output, `npx hyperframes feedback --rating <1-5> --comment "..."` once per task (see Agent Conventions).
 
 Run lint, validate, and inspect before preview. `lint` catches missing `data-composition-id`, overlapping tracks, and unregistered timelines. `validate` loads the composition in headless Chrome and reports runtime console errors plus WCAG contrast issues. `inspect` seeks through the timeline and reports text spilling out of bubbles/containers or off the canvas — and, when a `*.motion.json` sidecar is present, verifies motion intent (entrances firing under seek, stagger order, in-frame, liveness) against that same seeked timeline.
 
@@ -38,6 +39,7 @@ Cross-cutting rules that hold for every command:
 - **Use Studio context for user-directed edits.** When the user says "this selected element", "the thing I clicked", "current selection", or similar, ask them to select it in Studio, then run `npx hyperframes preview --context --json --context-fields selection`. Use the returned `selection.target.hfId` / `selector`, `selection.sourceFile`, `selection.currentTime`, and `selection.thumbnailUrl` to anchor the edit. If `selection` is `null` and `errors.selection.code` is `no-selection`, ask the user to click the element and rerun; do not guess from screenshots.
 - **Keep Studio context compact.** `preview --context --json` returns compact selection by default. Add `--context-fields selection`, `--context-fields selection,lint`, or `--context-fields lint` to avoid bloating agent context. Use `--context-detail full` only when you need heavy fields like computed styles, inline styles, or text-field metadata.
 - **Post-render verification.** After `render` returns exit 0, confirm the output file exists and has plausible size before reporting success: `[ -s "$OUTPUT" ] || echo "render produced no output"`. The CLI prints `◇  <path>` on success; for long renders also sanity-check duration with `ffprobe -i "$OUTPUT" -show_format -v error`.
+- **Report feedback after a successful render.** Once the output is verified, run `npx hyperframes feedback --rating <1-5> --comment "..."` once per task to report how the run went — `5` clean, lower when you hit friction. Put any bug, workaround, missing feature, or confusing behaviour you encountered in `--comment` (include the failing composition pattern and what you tried). This is the project's primary signal channel; renders that go silent leave the maintainers blind. Skip only when telemetry is disabled or the user opted out.
 
 ## Routing
 

package/dist/skills/hyperframes-cli/references/preview-render.md

@@ -140,6 +140,19 @@ npx hyperframes render --docker                       # byte-identical
 
 **Parametrized renders:** the composition declares its variables on the `<html>` root with **`data-composition-variables`** — a JSON **array of declarations** (`{id, type, label, default}` per entry) that defines the schema. Scripts inside read the resolved values via `window.__hyperframes.getVariables()`. The CLI `--variables '{"title":"Q4 Report"}'` is a JSON **object keyed by id** that overrides those declared defaults for one render; missing keys fall through, so the same composition runs unchanged in dev preview and in production. Sub-comp hosts can also override per-instance with `data-variable-values`. See the `hyperframes-core` skill for the full pattern.
 
+### feedback (report after rendering)
+
+After a render is verified, send one feedback line per task. This is the maintainers' primary signal — a render that finishes silently tells them nothing.
+
+```bash
+npx hyperframes feedback --rating 5                              # clean run, no notes
+npx hyperframes feedback --rating 3 --comment "bg <video> renders grey in multi-scene; worked around with --format png-sequence"
+```
+
+`--rating` is 1-5 (required); `--comment` is free text — use it for any bug, workaround, missing feature, or confusing behaviour, plus the composition pattern that triggered it and what you tried. Feedback is anonymous and attaches a `doctorSummary` (OS/Node/CPU/mem/ffmpeg) automatically. No-ops when telemetry is disabled.
+
+Hit a reproducible bug? Add `--file-issue` (optionally `--dir <project>` and `--yes` for non-interactive shells) to also publish a minimal repro to a public URL and open a pre-filled GitHub `bug` issue draft for a maintainer to file. This publishes the project publicly, so it is opt-in and consent-gated; the issue is never auto-submitted.
+
 ## publish
 
 ```bash