diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index ad4a458..783533f 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -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 diff --git a/docs/assets/playground/playground.css b/docs/assets/playground/playground.css index d69d175..10ad092 100644 --- a/docs/assets/playground/playground.css +++ b/docs/assets/playground/playground.css @@ -3,7 +3,7 @@ .pg-intro{padding:.5rem 0 1rem}.md-typeset .pg-eyebrow{font-size:.62rem;letter-spacing:.16em;font-weight:700;text-transform:uppercase;margin:0 0 .5rem;color:var(--md-accent-fg-color)} .md-typeset .pg-intro h1{font-size:2.7rem;line-height:1.1;margin:0 0 .7rem;font-weight:700;letter-spacing:-.06em}.pg-intro>p:last-child{color:var(--md-default-fg-color);font-size:.85rem;margin:.5rem 0} .pg-toolbar{display:flex;align-items:center;justify-content:space-between;gap:.75rem;padding:.8rem;background:var(--pg-paper);border:1px solid var(--pg-line);border-bottom:0;flex-wrap:wrap} -.pg-picker{display:flex;gap:.6rem;align-items:center;min-width:0}.pg-picker label{font-size:.62rem;font-weight:700;text-transform:uppercase;letter-spacing:.06em}.pg-picker select{min-width:0;max-width:100%;background:#fff;color:var(--pg-ink);font:inherit;font-size:.72rem;border:1px solid var(--pg-line);border-radius:0;padding:.55rem 2rem .55rem .65rem;appearance:auto} +.pg-picker{display:flex;gap:.6rem;align-items:center;min-width:0}.pg-picker label{font-size:.62rem;font-weight:700;text-transform:uppercase;letter-spacing:.06em}.pg-picker select{min-width:0;max-width:100%;background:#fff;color:var(--pg-ink);font:inherit;font-size:.72rem;border:1px solid var(--pg-line);border-radius:0;padding:.55rem 2rem .55rem .65rem;appearance:auto;color-scheme:light} .pg-actions{display:flex;gap:.45rem;align-items:center;flex-wrap:wrap}.fb-playground button,.pg-actions a{cursor:pointer;font:inherit;font-size:.68rem;font-weight:650;padding:.52rem .75rem;border:1px solid var(--pg-line);color:var(--pg-ink);background:#fff;line-height:1.35;text-decoration:none;white-space:nowrap} .pg-export{display:flex;align-items:center;justify-content:flex-end;gap:.65rem;flex-wrap:wrap;padding:.6rem .8rem;background:var(--pg-paper);border:1px solid var(--pg-line);border-bottom:0}.pg-export .pg-picker select{padding-top:.4rem;padding-bottom:.4rem} .fb-playground button:hover,.pg-actions a:hover{border-color:var(--pg-ink);background:#e8eee9}.fb-playground .pg-primary{background:var(--pg-ink);color:#fff;border-color:var(--pg-ink)}.fb-playground .pg-primary:hover{background:#245746;color:#fff}.pg-primary span{margin-left:.7rem} diff --git a/docs/assets/walkthroughs/invoice-20261102/captions.vtt b/docs/assets/walkthroughs/invoice-20261102/captions.vtt new file mode 100644 index 0000000..2dd35fb --- /dev/null +++ b/docs/assets/walkthroughs/invoice-20261102/captions.vtt @@ -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. diff --git a/docs/assets/walkthroughs/invoice-20261102/poster.png b/docs/assets/walkthroughs/invoice-20261102/poster.png new file mode 100644 index 0000000..1307515 Binary files /dev/null and b/docs/assets/walkthroughs/invoice-20261102/poster.png differ diff --git a/docs/assets/walkthroughs/invoice-20261102/walkthrough.mp4 b/docs/assets/walkthroughs/invoice-20261102/walkthrough.mp4 new file mode 100644 index 0000000..b8453cc Binary files /dev/null and b/docs/assets/walkthroughs/invoice-20261102/walkthrough.mp4 differ diff --git a/docs/guides/playground-walkthrough.md b/docs/guides/playground-walkthrough.md new file mode 100644 index 0000000..f4c8378 --- /dev/null +++ b/docs/guides/playground-walkthrough.md @@ -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. + + +

A silent walkthrough with on-screen instructions and optional English captions. Read the transcript or download the MP4.

+ +## 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 & Finch` to `Willow & 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). diff --git a/docs/playground.md b/docs/playground.md index ca83ddb..679bdaf 100644 --- a/docs/playground.md +++ b/docs/playground.md @@ -8,13 +8,13 @@ search: boost: 2 --- - +

A little code. A finished page.

Make it your own.

-

Edit an example or open your own HTML, CSS, images, and fonts. Everything runs on your device.

+

Edit an example or open your own files. Runs on your device. Watch a short walkthrough ↗

diff --git a/mkdocs.yml b/mkdocs.yml index d02ee29..82e0a16 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -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 diff --git a/tools/check_walkthrough_page.py b/tools/check_walkthrough_page.py new file mode 100644 index 0000000..0cfa46b --- /dev/null +++ b/tools/check_walkthrough_page.py @@ -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' + 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)) diff --git a/tools/walkthrough_server.py b/tools/walkthrough_server.py new file mode 100644 index 0000000..506b58c --- /dev/null +++ b/tools/walkthrough_server.py @@ -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