[AmroAlemam]

What

A skill rule for animating Arabic, Persian, Urdu and Hebrew text, skills/hyperframes-animation/rules/arabic-rtl-text.md:

• direction on the span container;
• word-level splits by default;
• a joiner-aware letter split (harakat, lam-alef, digit runs, ZWJ) when letters must move;
• an embedded Arabic font;
• the Safari ZWJ font caveat for Studio preview and published pages.

Plus an entry in rules-index.md (Text & Typography), a short note in hyperframes-creative/references/typography.md that none of the 18 bundled families covers Arabic, and the regenerated skills-manifest.json.

Why

split("") and inline-block word rows silently break Arabic: isolated letters and reversed word order. Lint catches neither, and no bundled font covers Arabic, so agents following the existing text recipes produce broken Arabic scenes.

Related work

Refs #5885 (this covers the skill-guidance part; the proposed lint warnings are not included).

How

Docs only, same frontmatter and section layout as the other rules. The recipe code was run as written in a HyperFrames 0.8.169 composition and rendered to MP4; the split output looks the same as plain text, including lam-alef, harakat and Eastern Arabic digits (renders in #5885).

Test plan

• Unit tests added/updated (docs only)
• Manual testing performed: hyperframes render before/after, see Arabic text: per-letter splits render isolated letters and word rows render reversed, with no lint warning #5885
• Documentation updated (if applicable)
• Comments follow CONTRIBUTING.md "Comments": the only comments are in the recipe snippets

Also run locally: scripts/lint-skills.ts (no issues), gen-skills-manifest.ts --check (in sync), oxfmt --check on the changed files (clean). The commit is signed (created through GitHub, shows Verified).

[vanceingalls]

Reviewed at 11430f86. Required CI is green at this head. Build, Typecheck, both Windows jobs and the runtime contract are path-skipped for a docs-only diff, and this is the only CI run at this SHA. The diff is docs and skills only: one new rule, one index line, one typography note and the regenerated skills-manifest.json hashes. It has no scripts, CI or workflow changes.

I checked the technical claims empirically. I rendered every case in the same chrome-headless-shell (152) the CLI uses, at 64px, and pixel-diffed it against the unsplit text.

Verified

• Word order: inline-block word spans with no dir render بالعالم مرحبا and ميلادي 2024 عام, which is reversed. Adding dir="rtl" on the container fixes it. Claim 1 holds.
• Naive split: split("") into inline-block breaks every join. 113–230% of the reference ink pixels differ on every line in all 6 fonts. Claim 2 holds.
• splitArabicLetters(): joins are preserved in Chrome. Across 6 fonts × 8 phrases (lam-alef, harakat, digits, an embedded Latin word, right-joining letters, hamza), 31 of 48 lines are pixel-identical to the unsplit text. The rest keep their connected forms but are a few px wider (2–7px per line), because cross-unit kerning and mark positioning (GPOS) is lost at the inline-block boundaries. The joining classes (RIGHT_JOINING, hamza as non-joining, joinsPrev/joinsNext) match Unicode ArabicShaping for the ranges listed.
• Fonts: Noto Sans Arabic, Noto Naskh Arabic, IBM Plex Sans Arabic, Cairo, Tajawal and Alexandria all map U+0627 and U+0640. In their Google Fonts TTFs, U+200D is mapped only in Noto Sans Arabic and Noto Naskh Arabic. It is absent from IBM Plex Sans Arabic, Cairo, Tajawal and Alexandria, exactly as the Safari note says. In Chrome, those four still render the ZWJ-padded units identically, so "MP4 renders are not affected" holds. The same is true for a text= subset of Cairo from Google, which is what the compiler fetches. I couldn't test the Safari fallback claim itself here.
• Bundled families: none of the 18 bundled families has an Arabic subset on Google Fonts.

Non-blocking

• rules/arabic-rtl-text.md, "look exactly like the unsplit word": this slightly overstates it. Some words come out a few px wider, as above. And in fonts with a contextual Allah ligature (Cairo, Tajawal, Alexandria), الله loses the ligature (the shadda with superscript alef disappears) once it's split into letters. Suggest "keeps every letter joined" plus a line saying to keep الله as one unit, the same way the rule treats lam-alef.
• typography.md and the rule's description: Hebrew is lumped in with "none of the bundled families covers it". Open Sans (bundled) has a Hebrew subset, and bundledFamilyFaceRules in deterministicFonts.ts fetches non-Latin subsets as a supplement, so Hebrew in Open Sans does render. The Arabic statement is correct.
• splitArabicLetters usage: line.innerHTML = … interpolates the raw text, so a < or & in data-driven text breaks the markup. Building spans with textContent avoids that in a recipe agents will copy verbatim.
• LTR_RUN doesn't include spaces, so an embedded multi-word Latin phrase (Hyper Frames) becomes separate neutral inline-block runs, and the RTL line reverses their order. A one-line caveat, or wrapping Latin phrases in a single <bdi>-style unit, would cover it.

Verdict: APPROVE
Reasoning: The bidi and joining claims and the recipe all reproduce in our Chrome render path, and the font coverage claims match the font files. The remaining points are wording and edge-case refinements in a docs-only change.

— Via

[AmroAlemam]

Thanks so much for the careful review, @vanceingalls! I took all four suggestions:

• الله stays whole: the split examples now keep the word as one piece, since splitting it breaks the ligature in fonts like Cairo and Alexandria.
• Spans are built with textContent: the per-letter example no longer builds spans with innerHTML.
• Multi-word Latin phrases stay together: a run like "Open Source" inside Arabic is treated as one LTR piece instead of being split word by word.
• Hebrew note: the typography reference now says Open Sans covers Hebrew.

I also toned down the "looks exactly like" line so it doesn't overpromise. Thanks again, this made the rule a lot better.

[miguel-heygen]

Approving at this head. All four earlier points are fixed: the Allah unit, the switch to createElement plus textContent, the multi word Latin run, and the honest wording about a split line coming out a few pixels wider. The typography note and the rule now agree that Hebrew renders with bundled Open Sans.

I lifted splitArabicLetters out of the rule exactly as written and ran it. Allah stays whole, "اللهم" correctly does not match, the digit run and "Hyper Frames" each come out as one unit, lam alef holds, and the joiner pass still runs over the new unit kinds, so "بالله" keeps its join. The i += 3 lands on the right grapheme.

One thing for a maintainer rather than for you: only the Graphite and WIP checks have run at this head, so the skills manifest in sync job has not seen the regenerated hashes. Worth letting the workflow run before merge.

Thanks for writing this up, and welcome. It is a genuinely useful rule.

[jrusso1020]

Reviewed at 6474a5f3. This needs a new home rather than a plain rebase, and that's not something you did wrong. #5651 (merged 2026-10-21) retired the workflow skills. skills/hyperframes-animation/ and skills/hyperframes-creative/ no longer exist on main, including rules-index.md and references/typography.md. All three files this PR edits are gone, which is why the branch conflicts.

The guidance itself is still missing from main: nothing under skills/ mentions RTL or Arabic. Vance and Miguel both approved the content, so it's worth carrying forward. The closest home in the new layout is skills/hyperframes/references/, for example a short section in captions.md or look.md, kept as short as the new references are. Since the skills were just restructured, a quick check with Miguel on where it should live would save you a second rewrite.

Need: yes, but not in the files it targets · Size: would need trimming for the new references · Reuse: fold it into an existing reference, not a new rule file · Simpler: one section instead of a 153-line rule

— Rames

[jrusso1020]

Thanks for this and for working through the review. #5651 removed the three files this edits, so it can't merge as is. We'd still like the Arabic/RTL guidance: a short section in skills/hyperframes/references (captions.md or look.md) would be the right home.

[AmroAlemam]

Thanks @jrusso1020, that makes total sense, and thanks for keeping the guidance alive. @miguel-heygen, before I rewrite it: would you rather the Arabic/RTL section live in captions.md or look.md? I'm leaning toward captions.md since most of it is about splitting and staggering words, and I'll open a fresh PR there with a trimmed version (about 25 lines) once you let me know.

Amro