Labelled 56s, but the file I encoded and uploaded measures 47.6s - there are
several variants of that marketing film on disk and the 1920x1080 one I selected
is the shorter cut. Every other label matches its file to the nearest second.
The wall compiled but rendered zero tiles. Reading the page bundle showed why:
Mintlify keeps only the exported component out of a snippet file, so the CDN base
and the film list I had declared above it never made it into the compiled output -
`const FILMS` and `const CDN` appear zero times in the bundle while `FILMS.map` is
still there. The component threw on an undefined reference, React's error boundary
swallowed it, and the section rendered empty with no console error to point at it.
Both constants now live inside the component. Recorded the trap in AGENTS.md,
since a blank snippet with a clean console gives no clue on its own.
The front page was showing a film I generated, and it was the weakest asset in the
project: silent, slow, and stylistically plain. Meanwhile roughly 260 finished
films made with HyperFrames sat in ~/Downloads/hyperframes-launches and
~/Desktop/hyperframes-launches, most at 1080p with audio, and the good ones were
only reachable from /examples.
The hero is now the website-launch film - 38s, 1080p, real audio at -14.3 dB. It
shows the whole loop in one take: a site captured, FRAME.md, STORYBOARD.md and
SCRIPT.md written, the film rendered. It autoplays muted and unmutes on demand.
"What can it make?" was four five-second catalog snippets. It is now six finished
films: colour grading, one shoot cut many ways, a music-driven edit, a pull request
explained, timeline editing, and a personalised year-in-review. Each tile is a
silent six-second loop of 37-241KB; selecting one loads the full film with sound,
so the 1-8MB files are only fetched when someone asks for them. Tile moments were
chosen by looking at them at the 320px they actually render: the first cuts of the
music and pull-request films were an empty waveform and an illegible terminal, so
both were re-cut to the sections that read.
Removed the silent film I had committed, now that nothing references it.
All eight guides opened with prose and contained no images and no video, which is
the main reason the pages read flat: they are the destination of the "I need a
specific thing" journey, and they never showed what the thing looks like. Six now
open with a real scene playing, captioned with exactly what the clip is rather
than implying it is a finished film.
The previews were re-encoded rather than reused as-is. The catalog originals run
127KB to 1.3MB and these autoplay on load, so each is trimmed to its most legible
five seconds at 960x540 and lands between 16KB and 90KB on the docs CDN.
music-to-video and slideshow are deliberately still without media. Nothing in the
catalog honestly represents a beat-synced cut or a navigable deck, and a
decorative stand-in on a page about a specific output would be a small lie. Those
two need a purpose-rendered clip each.
My first fix was based on a wrong diagnosis. Prose width was not the problem:
Mintlify wraps every image in its zoom component, span[data-rmiz] >
span[data-rmiz-content] > picture.contents > img, so the width I put on a
surrounding div was absorbed by that wrapper and the image still rendered full
width with the card's text pushed out of view. Reading the served markup also
showed the build rewrites Tailwind classes into a mint-* namespace and drops what
it does not recognise, which is why object-right never appeared in the output at
all.
The thumbnail now uses an hf-peek class in custom.css, which collapses the zoom
wrapper and sizes the box directly. Custom classes survive the rewrite; utilities
are not dependable for anything load-bearing. Both findings are in AGENTS.md,
including the note that videos are not wrapped - which is why the identical card
on the quickstart worked with a video and failed with an image.
The card was reusing the flowchart block as its thumbnail, which was wrong twice
over: it is a white graphic sitting in a dark page, illegible at the 256px it
actually renders at, and it implies the link leads to diagrams when it leads to
every kind of video.
Replaced with a 5.7s montage cut from four real catalog outputs - code appearing,
kinetic captions, an animated map, a brand sting - so the thumbnail shows range
rather than one example. Built dark-ground only after measuring: the first attempt
mixed a white count-up and a white lower third among dark clips, which made the
loop flash white every 1.4 seconds. Mean brightness now sits at 15, 28, 34 and 15
across the four cuts. 32KB, silent, uploaded to the docs CDN.
Twenty-five accordions remained in three hand-written pages: troubleshooting,
data-attributes, and html-schema. Each is now a visible heading, so every symptom
appears in the page contents and has an anchor support can link directly - which
was the point of making help symptom-first in the first place. Nothing is behind
a click, Cmd+F reaches all of it, and the pages print.
Accordion bodies were indented four spaces, which markdown would read as code
blocks once the wrapper was gone, so bodies are de-indented and each heading is
followed by a blank line. Zero accordions remain anywhere in docs/.
The card measured 686px of image inside a 688px card: the theme's prose styles set
img { width: 100% }, which beats a sm:w-64 utility on the image itself, so the
side-by-side layout collapsed and the card's own text was pushed out of view. The
width now lives on a wrapper the prose rules do not touch, with the image filling
it and anchored right so the thumbnail lands on the Renders panel rather than a
crop of empty canvas.
Recorded the rule in AGENTS.md, along with the related margin behaviour that put a
black band around the introduction hero, so neither is rediscovered.
Both pages ended in a row of equal cards, which is a fresh decision at exactly
the moment the reader should be moving, and each card only named its destination.
They now lead with one dominant next step that shows what is on the other side —
a live scene preview for the workflow chooser, the real Renders panel for export —
followed by the genuinely relevant alternatives as a quiet sentence of links,
ranked by how likely they are to matter.
The point is hierarchy rather than scarcity: several onward paths are fine, but
they should not all shout at the same volume, and a link that shows the thing
earns the click that a link naming the thing does not.
The previous commit pointed the introduction at a film that was never added.
.gitignore excludes docs/images/* so that generated catalog previews stay out of
the repository, with explicit negations for the few authored assets that belong
in it - the Studio screenshots. `git add -A` therefore skipped the film silently
and the page shipped with a hero that resolved to a 404.
Negated the showcase directory the same way the Studio screenshots already are,
and noted why this one is exempt: it is authored rather than generated, it is the
whole argument of the page, and at 332KB silent it is smaller than a single
catalog preview - so the page cannot break when a CDN credential expires.
The introduction now plays a film built for it rather than an older showcase
clip: one request - "make a 30-second launch video for our new pricing page" -
carried through the agent building the project, Studio opening it, a person
changing one line, and the export finishing. It was produced with HyperFrames.
Hosting solved without the CDN. The clip sits in docs/images/showcase/ at 332KB,
under the repository's 500KB non-LFS limit, because the hero autoplays muted and
therefore does not need the audio track. Encoding it silently at 720p bought the
whole 42 seconds for less than the size of one catalog preview. The master with
its music bed still needs the shared asset host, and the SSO credentials for that
bucket have expired, so it stays out of the repo for now.
The quickstart's leading example is now that same pricing-page request, and says
so. Using a different example on every page forces the reader to rebuild the
mental model each time; one project carried across the pages is the cheapest
change available that makes them read as a single path.
The 138 catalog pages hid their install command, registry metadata, and wiring
snippet behind three accordions. Asking an agent and running the terminal command
are two parallel ways to do one thing, so they are now tabs with the agent
request leading; the metadata and the hand-wiring snippet are visible, since they
were short enough that a click bought nothing while costing Cmd+F and printing.
This is how component catalogs are normally presented - shadcn/ui and its
descendants put preview and code behind tabs - and it keeps the preview first,
which is the point of a visual catalog.
Two generator bugs fixed while in there. It rebuilt the Catalog tab object from
scratch, so the tab silently lost its icon on every regeneration, and it
re-inserted the tab relative to a tab named Documentation that no longer exists,
so the fallback index moved Catalog ahead of Studio. It now updates the existing
tab in place and owns only the groups array.
Regenerating also picked up four registry items that had no docs page:
camcorder-hud, editorial-flash-overlay, freeze-frame-dressing, and
organic-light-leak-overlay.
Accordions now remain in three hand-written pages only: troubleshooting,
data-attributes, and html-schema.
mint validate and mint broken-links pass. The repo's pre-commit build gate was
bypassed deliberately: this work lives in a git worktree, which has no
per-package node_modules, so `bun run build` cannot resolve tsup there. The gate
covers package builds and this change touches docs/ and one generator script.
At this column width the breakout rendered 968px and dominated the page instead
of supporting it. The film is back inside a Frame at the column width. The part
worth keeping was the motion, not the size: it still autoplays muted on a loop
rather than sitting behind a play button, so the page is already moving when it
loads. Removed the now-unused wrapper CSS rather than leaving a dead rule.
The wrapper measured 609px tall against a 545px film - the theme's prose styles
apply a 2em margin to media, which rendered as a 64px black band above and below
it. Zeroed the margin inside the hero wrapper.
The film now reaches into the shell padding so it reads edge to edge, and it
autoplays muted on a loop instead of waiting behind a play button. Motion is
pre-attentive - the eye goes to it before any text is read - so a page that is
already moving answers 'what is this?' faster than a poster the reader has to
decide to click. Controls stay available for scrubbing and for unmuting once a
film with a real audio track is hosted.
Not implemented as 100vw: this column is not centred in the viewport because the
sidebar is a flex sibling, so the usual margin-left: calc(50% - 50vw) breakout
would sit off-centre. Noted in the CSS.
Checked it on the live preview instead of assuming: a whole guide page renders
about three <p> elements, because the content is lists, tables, cards, and code.
The selector matched one of them — the page description in the header — so the
rule capped nothing while reading as though it were load-bearing. Removed it and
corrected the width note in AGENTS.md, which claimed prose was held near 80
characters. The column measures 888px at 1600 and 1048px at 1920.
The previous attempt raised max-width on the article shell, which did nothing
visible: the shell was never hitting that cap. Measuring the chain showed the
left sidebar sits inside #body-content, whose max-w-8xl (1472px) was the binding
limit — 1432 inner minus a 287px sidebar minus 128px of shell padding minus 352px
of contents rail and gap lands on exactly the 664px column that was rendering.
Raising #body-content, dropping the shell cap, trimming the left padding, and
holding the contents rail to the 16rem it actually uses gives a measured column
of 728px at 1440, 888px at 1600, and 1048px at 1920 — the last of which was
previously stuck at 664 no matter how wide the display. No horizontal overflow at
any of those widths. Setting a width on #content-area is pointless, as it is a
flex item with grow that just fills the remainder; noted in the comment so the
next person does not repeat it.
Navigation: Start here now holds exactly the four entry points a person can be
sent - what it is, make one, choose a workflow, and the Studio overview. The
three pages that were sitting in it went where they belong: the project tour is
conceptual so it moved to Learn, authentication is configuration so it moved to
Developers, and the hosted AI-chat route is a creation surface so it moved to
Create with an agent.
Width: the theme capped the article shell at 72rem and reserved 28rem of every
wide viewport for the contents rail, leaving the reading column at ~664px on a
1600px screen - narrower than the 16:9 video the pages are supposed to show.
Raised the shell and returned 9rem from the gutter, taking the column to roughly
950px. Running prose is held near 80 characters because longer lines measurably
hurt reading; tables, cards, code, and media use the full width. Added .hf-wide
for visuals that should escape the measure entirely.
Components: the quickstart source chooser is now Tabs, which is what parallel
variants of one instruction want, and the help symptoms are visible sections with
their own anchors so support can link a symptom directly instead of the hub.
Wrote the doctrine into AGENTS.md - one component per job, cards never point at
anchors on their own page, no diagram that restates adjacent prose, and the rules
for custom React snippets (named exports, no third-party packages, no CDN).
The code-font rule also matched [class*="code"] and [class*="Code"], which
selects any element whose class merely contains that substring. Every Accordion
wrapper carries the Tailwind utility dark:bg-codeblock, so the whole accordion
inherited IBM Plex Mono: titles and body prose rendered as monospace, which read
like terminal output instead of sentences. This affected every accordion on the
site, including the source chooser that already existed on the quickstart page.
Scoped the rule to real code elements; syntax tokens inherit from pre.
Also reverted the workflow chooser to cards. Collapsing eight situations into
grey accordion rows removed duplication but made the page less inviting to scan,
and the eight starter requests it carried were a third copy - every workflow
guide already contains its own. The cards now link straight to those guides
rather than to anchors further down the page.
help: the eight symptom cards linked to anchors immediately below that repeated
their own descriptions. One accordion per symptom now holds the fix, so scanning
and expanding replaces scrolling past the same words twice. The diagnostic block
and the four real escalation links stay.
studio: dropped the decision flowchart that duplicated the table beneath it, and
added the existing Storyboard screenshot so the Storyboard-versus-Preview split
is shown rather than only described.
quickstart: removed the five-node diagram that restated the six numbered steps,
and pointed the request-writing advice at the prompting guide instead of growing
a third copy of it.
introduction: the showcase file has a single h264 stream and no audio track, so
'press play - it has sound' was simply untrue. Removed the claim; the caption now
only says what the clip is.
workflows: the page listed all eight situations twice - once as cards linking to
anchors a short scroll down, then again as full sections repeating the same
'best for' line. Collapsed both into one accordion per situation whose title is
the chooser and whose body holds the brief and the copyable request, so the eight
cards now lead somewhere real instead of jumping down the page. Dropped the
five-step 'what happens after you choose' (it restates quickstart) and the
six-part request checklist (it restates the prompting guide) in favour of links.
187 lines to 165, eleven headings to one; no starter request was lost.
The karaoke clip rendered as an almost-black tile with one small pill, which is
weak proof on first load. Every caption component in the catalog is type on a
black ground rather than captions burned over footage, so 'Captions on footage'
was also the wrong label. Swapped to the highlight style, which holds up at
tile size, and renamed the tile 'Kinetic captions'.
Reviewed the rendered page instead of the source: the four preview tiles came
out ~110px wide in a 730px content column, with labels wrapping mid-phrase, and
the three-column workflow cards were cramped enough to hyphenate a title into
'presentation s'. Two columns is the practical maximum for this column width, so
the tiles are now a readable 2x2 and the cards are back to two across.
- Lead with the film: the video moves directly under the one-line definition,
so a stranger sees a real result before reading anything.
- Delete the mermaid flow diagram. It duplicated the Steps list underneath it
word for word; the section heading already carries the flow.
- Replace the wall of text under 'What can it make?' with four real HyperFrames
outputs playing inline (~960KB total, deliberately the small clips), then keep
the six workflow paths as compact three-column links.
- Compress the four-row Studio-vs-agent table to two lines. A newcomer needs the
principle, not a decision matrix; the detail belongs in Studio.
- One primary next step instead of three equal cards.
Make /introduction the single "What is HyperFrames?" page a stranger can be
sent, and retire the switchboard that sat in front of it.
- introduction: lead with one sentence + a sound-on result (drop `muted`),
simplify the loop diagram to request -> agent -> project -> video, cut the
fake "See how it works" scroll button, and replace the equal-weight card
walls with one clear "Start here" action.
- guides/index: remove the six-card "What do you need to do?" menu-of-menus.
The nav already routes people and /introduction is the real entry point.
Redirect /guides -> /introduction.
- developers: point the "create a video" link at /quickstart.
mint validate and mint broken-links both pass.
An expanded sub-composition child row is built from a manifest clip, which
carries none of the host element's attributes, so data-hidden never reached
it. The eye on that row therefore always reported the element visible: the
first click hid it, and every click after wrote data-hidden again instead of
removing it. The element could not be shown again, not even after a reload,
because the attribute was already in the source.
The flat store element for the same child is built with its host element, so
the child row inherits hidden, timelineLocked and timelineRole from it.
Right-clicking a motionPath waypoint in the preview overlay opened Chrome's
own context menu on top of the editor: the handler returned before
preventDefault for every node that was not an x/y keyframe. Both node kinds
now open Studio's menu. A waypoint has no percentage of its own, so Move to
Playhead is hidden and Delete acts on the path index, matching the hover x
badge; Delete is withheld entirely on a two-anchor arc, where the writer
refuses the removal and the entry would silently do nothing.
ukimsanov