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
8 changes: 8 additions & 0 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -1190,6 +1190,14 @@ jobs:
- name: Verify the focused React preview recipe download and source hashes
run: python tools/check_react_preview_recipe.py
- run: python -m mkdocs build --strict
- name: Verify the invoice walkthrough and preserve playground edits
run: python tools/check_walkthrough_page.py --site site --out output/playground-walkthrough --browser chrome
- uses: actions/upload-artifact@v4
if: always()
with:
name: playground-walkthrough-verification
path: output/playground-walkthrough/
retention-days: 14
- name: Materialize the verified published-wheel CSS evidence
run: python tools/prepare_css_corpus_site.py site
- run: python tools/check_site.py site
Expand Down
2 changes: 1 addition & 1 deletion docs/assets/playground/playground.css

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

33 changes: 33 additions & 0 deletions docs/assets/walkthroughs/invoice-20261102/captions.vtt
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
WEBVTT

00:00:00.000 --> 00:00:04.000
Customize an invoice in Fullbleed's free
HTML and CSS playground.

00:00:04.000 --> 00:00:07.760
Open the playground. Choose Northstar
invoice.

00:00:07.760 --> 00:00:14.480
Change the recipient from Maple & Finch to
Willow & Finch.

00:00:14.480 --> 00:00:22.200
Add a CSS rule to change the invoice
heading color.

00:00:22.200 --> 00:00:30.240
Choose Render PDF to preview the new
recipient and heading color.

00:00:30.240 --> 00:00:34.600
Choose Download PDF to save the finished
invoice.

00:00:34.600 --> 00:00:42.240
Choose Node.js, then Download project to
keep the editable source.

00:00:42.240 --> 00:00:50.240
Extract the Node.js ZIP. Run npm ci
--ignore-scripts, then npm run render.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file not shown.
53 changes: 53 additions & 0 deletions docs/guides/playground-walkthrough.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
---
title: Customize an invoice in the playground
description: "Watch a short Fullbleed walkthrough: edit an invoice with HTML and CSS, download the PDF, and run the exported Node.js project locally."
---

# Customize an invoice in the playground

Start with the Northstar invoice in the [free playground](../playground.md).
Change its recipient and heading color, download the PDF, then take the editable
project into your own workflow. No account is needed to try it.

<video id="invoice-walkthrough" controls preload="none" playsinline width="1920" height="1080" style="display:block;width:100%;height:auto;aspect-ratio:16/9" poster="../../assets/walkthroughs/invoice-20261102/poster.png" aria-label="Customize a Fullbleed invoice with HTML and CSS" aria-describedby="invoice-walkthrough-note">
<source src="../../assets/walkthroughs/invoice-20261102/walkthrough.mp4" type="video/mp4">
<track kind="captions" src="../../assets/walkthroughs/invoice-20261102/captions.vtt" srclang="en" label="English">
Your browser cannot play this video. Read the transcript below or download the MP4.
</video>
<p id="invoice-walkthrough-note">A silent walkthrough with on-screen instructions and optional English captions. <a href="#transcript">Read the transcript</a> or <a href="../../assets/walkthroughs/invoice-20261102/walkthrough.mp4" download>download the MP4</a>.</p>

## Transcript

The recording uses the fictional **Northstar invoice** example.

1. Open the [playground](../playground.md) and wait for the first PDF preview.
2. In the **HTML** editor, change `Maple &amp; Finch` to `Willow &amp; Finch`.
3. Select **CSS** and add this rule at the end:

```css
.invoice h1 { color: #b14d2e; }
```

4. Choose **Render PDF**. The preview now shows the new recipient and a terracotta
**INVOICE** heading.
5. Choose **Download PDF** to save the finished invoice.
6. Expand **Files and projects**, select **Node.js**, and choose **Download project**.
You can also choose Python when exporting your own project.

## Continue locally

Use **Node.js 22 or newer**. Extract the Node.js project ZIP and open a terminal in
the extracted folder. Run:

```bash
npm ci --ignore-scripts
npm run render
```

The renderer writes `output/document.pdf` and `output/preview/page-1.png`.
Edit `input.html` or `style.css`, then run `npm run render` again.
The ZIP includes the fonts, licenses, dependency lockfile, and renderer.

For application data and reusable templates, continue with the
[Node.js quickstart](../getting-started/node.md). For a Python export, follow the
commands in [Keep building](../playground.md#keep-building).
4 changes: 2 additions & 2 deletions docs/playground.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,13 +8,13 @@ search:
boost: 2
---

<link rel="stylesheet" href="../assets/playground/playground.css?v=font-cascade-2551">
<link rel="stylesheet" href="../assets/playground/playground.css?v=walkthrough-20261102">

<div class="fb-playground" id="playground">
<div class="pg-intro">
<p class="pg-eyebrow">A little code. A finished page.</p>
<h1>Make it your own.</h1>
<p>Edit an example or open your own HTML, CSS, images, and fonts. Everything runs on your device.</p>
<p>Edit an example or open your own files. Runs on your device. <a id="pg-walkthrough-link" href="../guides/playground-walkthrough/" target="_blank" rel="noopener" aria-label="Watch a short walkthrough (opens in a new tab)">Watch a short walkthrough ↗</a></p>
</div>
<div class="pg-toolbar">
<div class="pg-picker"><label for="pg-example">Start with</label><select id="pg-example" disabled><option value="invoice">Northstar invoice</option><option value="report">Common Ground report</option><option value="notice">Riverton notice</option></select></div>
Expand Down
1 change: 1 addition & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,7 @@ nav:
- Home: index.md
- Get started:
- Try in your browser: playground.md
- Watch the walkthrough: guides/playground-walkthrough.md
- Python quickstart: getting-started/quickstart.md
- Node.js quickstart: getting-started/node.md
- Rust quickstart: getting-started/rust.md
Expand Down
119 changes: 119 additions & 0 deletions tools/check_walkthrough_page.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,119 @@
"""Check the real generated walkthrough, captions, and playground link in Chromium."""
import argparse
from datetime import datetime, timezone
from functools import partial
from hashlib import sha256
from http.server import ThreadingHTTPServer
import json
from pathlib import Path
import re
import threading
from playwright.sync_api import sync_playwright, expect
from walkthrough_server import RangeRequestHandler

parser = argparse.ArgumentParser()
parser.add_argument('--site', type=Path, required=True)
parser.add_argument('--out', type=Path, required=True)
parser.add_argument('--browser', choices=['chromium', 'chrome'], default='chromium')
args = parser.parse_args()
site = args.site.resolve()
out = args.out.resolve()
assert (site / 'guides/playground-walkthrough/index.html').is_file()
assert not out.exists()
out.mkdir(parents=True)
assets = site / 'assets/walkthroughs/invoice-20261102'
asset_hashes = {name: sha256((assets / name).read_bytes()).hexdigest() for name in ['walkthrough.mp4', 'poster.png', 'captions.vtt']}
assert (assets / 'captions.vtt').read_text(encoding='utf8').startswith('WEBVTT\n')
server = ThreadingHTTPServer(('127.0.0.1', 0), partial(RangeRequestHandler, directory=str(site)))
thread = threading.Thread(target=server.serve_forever, daemon=True)
thread.start()
base = f'http://127.0.0.1:{server.server_address[1]}'
errors = []
results = []
try:
with sync_playwright() as pw:
browser = pw.chromium.launch(**({'channel': 'chrome'} if args.browser == 'chrome' else {}))
browser_version = browser.version
try:
for label, viewport in [('desktop', {'width': 1280, 'height': 900}), ('mobile', {'width': 390, 'height': 844})]:
context = browser.new_context(viewport=viewport, color_scheme='light')
try:
media_requests = []
context.on('page', lambda page: page.on('pageerror', lambda error: errors.append(str(error))))
context.on('request', lambda request: media_requests.append(request.url) if request.url.endswith('/walkthrough.mp4') else None)
playground = None
if label == 'desktop':
playground = context.new_page()
response = playground.goto(base + '/playground/', wait_until='domcontentloaded')
assert response and response.status == 200
expect(playground.locator('#pg-html')).to_be_enabled(timeout=120000)
expect(playground.locator('#pg-download')).to_have_attribute('href', re.compile('^blob:'), timeout=120000)
edited = playground.locator('#pg-html').input_value() + '\n<!-- Keep this edit while watching the walkthrough. -->'
playground.locator('#pg-html').fill(edited)
link = playground.locator('#pg-walkthrough-link')
expect(link).to_have_attribute('target', '_blank')
assert 'noopener' in link.get_attribute('rel').split()
with playground.expect_popup() as opened:
link.click()
page = opened.value
page.wait_for_load_state('domcontentloaded')
assert page.url == base + '/guides/playground-walkthrough/'
assert playground.locator('#pg-html').input_value() == edited
else:
page = context.new_page()
response = page.goto(base + '/guides/playground-walkthrough/', wait_until='domcontentloaded')
assert response and response.status == 200
video = page.locator('#invoice-walkthrough')
expect(video).to_be_visible()
assert video.get_attribute('preload') == 'none'
assert video.get_attribute('autoplay') is None
assert video.evaluate('(video) => video.controls')
expect(page.locator('#transcript')).to_be_visible()
text = page.locator('main').inner_text()
expect(page.locator('main h1')).to_contain_text('Customize an invoice in the playground')
expect(page.locator('meta[name="description"]')).to_have_attribute('content', 'Watch a short Fullbleed walkthrough: edit an invoice with HTML and CSS, download the PDF, and run the exported Node.js project locally.')
assert 'title: Customize' not in text and 'description: Watch' not in text
for required in ['Willow', 'Node.js 22 or newer', 'npm ci --ignore-scripts', 'npm run render', 'output/document.pdf']:
assert required in text, required
assert not media_requests, 'Video downloaded before the viewer requested playback.'
assert page.evaluate('document.documentElement.scrollWidth <= innerWidth + 1')
await_fonts = 'document.fonts.status === "loaded"'
page.wait_for_function(await_fonts)
page.screenshot(path=str(out / f'{label}-poster.png'), full_page=True)
video.evaluate('(video) => video.play()')
page.wait_for_function('document.querySelector("#invoice-walkthrough").currentTime >= 1', timeout=30000)
video.evaluate('(video) => video.pause()')
media = video.evaluate('(video) => ({width:video.videoWidth,height:video.videoHeight,duration:video.duration,time:video.currentTime,error:video.error?.message||null,frames:video.getVideoPlaybackQuality().totalVideoFrames})')
assert media['width'] == 1920 and media['height'] == 1080 and 15 < media['duration'] < 120
assert media['time'] >= 1 and media['frames'] > 0 and not media['error']
assert media_requests
track = video.locator('track')
expect(track).to_have_attribute('kind', 'captions')
expect(track).to_have_attribute('srclang', 'en')
video.evaluate('(video) => { video.textTracks[0].mode="hidden"; }')
page.wait_for_function('document.querySelector("#invoice-walkthrough").textTracks[0].cues?.length > 0', timeout=15000)
captions = video.evaluate('(video) => Array.from(video.textTracks[0].cues, cue => ({start:cue.startTime,end:cue.endTime,text:cue.text}))')
assert len(captions) >= 5 and captions[0]['start'] == 0
assert all(0 <= cue['start'] < cue['end'] <= media['duration'] + 0.1 for cue in captions)
assert abs(captions[-1]['end'] - media['duration']) < 0.15
page.screenshot(path=str(out / f'{label}-playback.png'), full_page=True)
if playground:
page.close()
assert playground.locator('#pg-html').input_value() == edited
results.append({'viewport': label, 'media': media, 'captionCues': len(captions), 'mediaDeferredUntilPlayback': True,
'horizontalOverflow': False, 'playgroundEditsPreserved': True if playground else None})
finally:
context.close()
assert not errors
finally:
browser.close()
finally:
server.shutdown()
server.server_close()
thread.join(timeout=5)
assert not thread.is_alive()
record = {'at': datetime.now(timezone.utc).isoformat(), 'status': 'passed', 'assets': asset_hashes,
'results': results, 'pageErrors': errors, 'serverStopped': True, 'browser': args.browser, 'browserVersion': browser_version,
'scope': 'Actual generated page, desktop/mobile layout, playback and captions, optional link preserving source edits. No general accessibility-conformance claim.'}
(out / 'verification.json').write_text(json.dumps(record, indent=2) + '\n', encoding='utf8')
print(json.dumps(record))
67 changes: 67 additions & 0 deletions tools/walkthrough_server.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
"""A local static verification server with byte ranges for real media seeking."""
from http.server import SimpleHTTPRequestHandler
from pathlib import Path
import re


class RangeRequestHandler(SimpleHTTPRequestHandler):
extensions_map = {**SimpleHTTPRequestHandler.extensions_map, '.mp4': 'video/mp4', '.vtt': 'text/vtt'}

def log_message(self, format, *args):
pass

def end_headers(self):
if getattr(self, '_regular_file', False):
self.send_header('Accept-Ranges', 'bytes')
super().end_headers()

def send_head(self):
self._remaining = None
path = Path(self.translate_path(self.path)).resolve()
if not path.is_relative_to(Path(self.directory).resolve()):
self.send_error(403)
return None
self._regular_file = path.is_file()
value = self.headers.get('Range') if self.command == 'GET' else None
if not value or not self._regular_file:
return super().send_head()
size = path.stat().st_size
match = re.fullmatch(r'bytes=(\d*)-(\d*)', value)
start, end = 0, -1
if match and any(match.groups()) and size:
first, last = match.groups()
if first:
start = int(first)
end = min(int(last), size - 1) if last else size - 1
elif int(last) > 0:
start, end = max(0, size - int(last)), size - 1
if not 0 <= start <= end < size:
self.send_response(416)
self.send_header('Content-Range', f'bytes */{size}')
self.send_header('Content-Length', '0')
self.end_headers()
return None
stream = path.open('rb')
stream.seek(start)
self._remaining = end - start + 1
self.send_response(206)
self.send_header('Content-Type', self.guess_type(str(path)))
self.send_header('Content-Length', str(self._remaining))
self.send_header('Content-Range', f'bytes {start}-{end}/{size}')
self.send_header('Last-Modified', self.date_time_string(path.stat().st_mtime))
self.end_headers()
return stream

def copyfile(self, source, output):
try:
if self._remaining is None:
return super().copyfile(source, output)
while self._remaining:
chunk = source.read(min(65536, self._remaining))
if not chunk:
break
output.write(chunk)
self._remaining -= len(chunk)
except (BrokenPipeError, ConnectionResetError):
# Browsers may stop an earlier transfer when requesting another range.
pass
Loading