Merge pull request #185 from fullbleed-engine/docs/component-template-install

Open local documents and assets in the PDF playground

Author: krflol

.github/workflows/docs.yml

@@ -923,6 +923,7 @@ jobs:
       - name: Verify downloadable playground projects
         run: |
           python -m pip install fullbleed==2.5.40 pypdf==6.19.0 pypdfium2==5.14.0 Pillow==12.3.0
+          node tools/test_playground_local_files.mjs
           node tools/verify_project_export.mjs
           python -I tools/verify_project_export.py
           python -I tools/verify_node_project_export.py
@@ -1214,6 +1215,16 @@ jobs:
           retention-days: 14
       - name: Verify the built playground PDF and project downloads
         run: python tools/check_playground_ui.py --site site --out output/playground-ui --browser chrome
+      - name: Import local assets and replay both downloaded projects
+        run: python tools/check_playground_local_files.py --site site --out output/playground-local-files
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: playground-local-files-verification
+          path: |
+            output/playground-local-files/
+            !output/playground-local-files/**/node_modules/**
+          retention-days: 14
       - uses: actions/upload-artifact@v4
         if: always()
         with:

docs/assets/playground/app.js

@@ -3,21 +3,24 @@ import { prepareExample } from './examples.js';
 
 const assetGeneration = new URL(import.meta.url).search;
 const { buildProject } = await import(`./project-export.js${assetGeneration}`);
+const { readSelection, validateSource } = await import(`./local-files.js${assetGeneration}`);
 
 const el = id => document.getElementById(`pg-${id}`);
 const html = el('html'), css = el('css'), picker = el('example');
 const projectLanguage = el('project-language');
 const originals = new Map(), edits = new Map();
 let current = 'invoice', worker = null, deadline = null, pageIndex = 0, pages = [], pdfUrl = null;
 let renderedSource = null;
+let localAssets = [], assetVersion = 0;
 
 function status(message, error = false) {
   el('status').textContent = message;
   el('status').dataset.error = String(error);
 }
 
 function changedSinceRender() {
-  return !renderedSource || renderedSource.html !== html.value || renderedSource.css !== css.value;
+  return !renderedSource || renderedSource.html !== html.value || renderedSource.css !== css.value
+    || renderedSource.assetVersion !== assetVersion;
 }
 
 function setDownload(enabled) {
@@ -71,7 +74,7 @@ function fail(message) {
 
 function startRender() {
   if (worker) finish();
-  const source = { html: html.value, css: css.value };
+  const source = { html: html.value, css: css.value, assets: localAssets, assetVersion };
   if (new TextEncoder().encode(source.html + source.css).length > 200000) {
     status('This playground accepts up to 200 KB of HTML and CSS combined.', true);
     return;
@@ -113,7 +116,7 @@ function startRender() {
       finish();
       setDownload(!changedSinceRender());
       if (changedSinceRender()) status('Source changed during rendering. Render again to update the PDF.');
-      else if (data.report.missing_glyphs) status(`PDF created, but ${data.report.missing_glyphs} character(s) have no glyph in the bundled fonts. Review the output before using it.`, true);
+      else if (data.report.missing_glyphs) status(`PDF created, but ${data.report.missing_glyphs} character(s) have no glyph in the available fonts. Review the output before using it.`, true);
       else status('Your PDF is ready. Change the design, or download it and keep building.');
     };
     worker.postMessage(source);
@@ -138,6 +141,70 @@ function saveText(name, content, type) {
   setTimeout(() => URL.revokeObjectURL(url), 1000);
 }
 
+function showAssets() {
+  const list = el('assets');
+  list.replaceChildren();
+  el('asset-count').textContent = `${localAssets.length} local ${localAssets.length === 1 ? 'asset' : 'assets'}`;
+  el('asset-help').hidden = localAssets.length === 0;
+  for (const asset of localAssets) {
+    const row = document.createElement('li'), name = document.createElement('code'), remove = document.createElement('button');
+    name.textContent = `assets/${asset.name}`;
+    remove.textContent = 'Remove';
+    remove.setAttribute('aria-label', `Remove ${asset.name}`);
+    remove.addEventListener('click', () => {
+      localAssets = localAssets.filter(item => item !== asset);
+      assetVersion++;
+      showAssets();
+      setDownload(!changedSinceRender());
+      status('Asset removed. Render again to update the PDF.');
+      el('open-files').focus();
+    });
+    row.append(name, remove);
+    list.append(row);
+  }
+}
+
+el('open-files').addEventListener('click', () => el('files').click());
+el('files').addEventListener('change', async () => {
+  const files = Array.from(el('files').files);
+  if (!files.length) return;
+  const snapshot = { current, html: html.value, css: css.value, assetVersion };
+  el('open-files').disabled = true;
+  status('Opening selected files on your device…');
+  try {
+    const selected = await readSelection(files, localAssets);
+    if (current !== snapshot.current || html.value !== snapshot.html || css.value !== snapshot.css || assetVersion !== snapshot.assetVersion) {
+      throw new Error('Your document changed while the files were opening. Choose the files again to apply them.');
+    }
+    const hasSource = selected.html !== null || selected.css !== null;
+    const nextHtml = selected.html ?? html.value;
+    const nextCss = selected.css ?? (selected.html !== null ? '' : css.value);
+    if (hasSource) validateSource(nextHtml, nextCss);
+    if (worker) finish();
+    if (hasSource) {
+      edits.set(current, { html: html.value, css: css.value });
+      current = 'custom';
+      originals.set(current, { html: nextHtml, css: nextCss });
+      edits.delete(current);
+      if (!picker.querySelector('option[value="custom"]')) picker.add(new Option('Your document', 'custom'));
+      picker.value = current;
+      html.value = nextHtml; css.value = nextCss;
+      el('reset').textContent = 'Reset document';
+      selectTab(selected.html !== null ? 'html' : 'css');
+    }
+    localAssets = [...localAssets, ...selected.assets];
+    assetVersion++;
+    showAssets();
+    clearOutput();
+    status('Files opened locally. Use assets/filename for images and font files, then Render PDF.');
+  } catch (error) {
+    status(error.message || 'Could not open the selected files.', true);
+  } finally {
+    el('files').value = '';
+    el('open-files').disabled = false;
+  }
+});
+
 for (const language of ['html', 'css']) {
   el(`${language}-tab`).addEventListener('click', () => selectTab(language));
   el(`${language}-tab`).addEventListener('keydown', event => {
@@ -168,7 +235,7 @@ el('next').addEventListener('click', () => showPage(pageIndex + 1));
 el('project').addEventListener('click', async () => {
   const button = el('project'), message = el('project-status');
   // Capture edits before downloading assets, even if the user keeps typing or switches examples.
-  const snapshot = { name: current, html: html.value, css: css.value, language: projectLanguage?.value ?? 'python' };
+  const snapshot = { name: current, html: html.value, css: css.value, language: projectLanguage?.value ?? 'python', assets: localAssets, assetVersion };
   button.disabled = true;
   button.textContent = 'Preparing project…';
   message.hidden = false;
@@ -177,7 +244,8 @@ el('project').addEventListener('click', async () => {
   try {
     const bytes = await buildProject(snapshot);
     saveText(`fullbleed-${snapshot.name}-${snapshot.language === 'node' ? 'node-' : ''}project.zip`, bytes, 'application/zip');
-    const newerEdits = current !== snapshot.name || html.value !== snapshot.html || css.value !== snapshot.css || (projectLanguage?.value ?? 'python') !== snapshot.language;
+    const newerEdits = current !== snapshot.name || html.value !== snapshot.html || css.value !== snapshot.css
+      || assetVersion !== snapshot.assetVersion || (projectLanguage?.value ?? 'python') !== snapshot.language;
     message.textContent = newerEdits
       ? 'Project downloaded with the source and language from when you clicked. Download again to include newer changes.'
       : 'Project downloaded. Extract the ZIP and follow its README to render locally.';
@@ -199,6 +267,7 @@ picker.addEventListener('change', () => {
   if (worker) finish();
   edits.set(current, { html: html.value, css: css.value });
   current = picker.value;
+  el('reset').textContent = current === 'custom' ? 'Reset document' : 'Reset example';
   const source = edits.get(current) || originals.get(current);
   html.value = source.html; css.value = source.css;
   clearOutput(); startRender();
@@ -218,7 +287,7 @@ try {
   if (originals.has(hashExample)) current = hashExample;
   picker.value = current;
   html.value = originals.get(current).html; css.value = originals.get(current).css;
-  for (const control of [html, css, picker, el('reset'), el('render'), el('project'), projectLanguage].filter(Boolean)) control.disabled = false;
+  for (const control of [html, css, picker, el('reset'), el('render'), el('project'), el('open-files'), projectLanguage].filter(Boolean)) control.disabled = false;
   for (const language of ['html', 'css']) { el(`save-${language}`).href = '#'; el(`save-${language}`).setAttribute('aria-disabled', 'false'); }
   startRender();
 } catch (error) { status(error.message, true); document.querySelector('.pg-output').setAttribute('aria-busy', 'false'); }

docs/assets/playground/local-files.js

@@ -0,0 +1,99 @@
+// SPDX-License-Identifier: MIT
+// Selected files remain in tab memory and the worker's virtual filesystem.
+export const limits = Object.freeze({ source: 200000, file: 8 * 1024 * 1024, assets: 20 * 1024 * 1024, count: 16 });
+const sourceExtensions = new Set(['html', 'htm', 'css']);
+const assetExtensions = new Set(['png', 'jpg', 'jpeg', 'svg', 'ttf', 'otf', 'txt']);
+const encoder = new TextEncoder();
+const decoder = new TextDecoder('utf-8', { fatal: true });
+
+export const assetKey = name => name.normalize('NFC').toLowerCase();
+export const isFont = name => /\.(ttf|otf)$/i.test(name);
+
+export function validateName(name) {
+  if (typeof name !== 'string' || !name || name.length > 120 || /^[. ]|[. ]$/.test(name)
+      || /[<>:"/\\|?*\x00-\x1f\x7f]/.test(name)
+      || /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(name)) {
+    throw new Error('Use a filename of up to 120 characters without folders or reserved filename characters.');
+  }
+  return name.split('.').at(-1).toLowerCase();
+}
+
+function text(bytes, name) {
+  try { return decoder.decode(bytes); }
+  catch { throw new Error(`${name} must be a UTF-8 text file.`); }
+}
+
+function validateAsset(asset) {
+  const ext = validateName(asset.name);
+  if (!assetExtensions.has(ext)) throw new Error('Choose PNG, JPEG, SVG, TTF, OTF, or TXT assets.');
+  const bytes = asset.bytes;
+  if (!(bytes instanceof Uint8Array) || !bytes.length || bytes.length > limits.file) {
+    throw new Error(`Each asset must contain data and be no larger than 8 MiB: ${asset.name}`);
+  }
+  const starts = values => values.every((value, i) => bytes[i] === value);
+  if (ext === 'png' && !starts([137, 80, 78, 71, 13, 10, 26, 10])) throw new Error(`${asset.name} is not a PNG file.`);
+  if (['jpg', 'jpeg'].includes(ext) && !starts([255, 216, 255])) throw new Error(`${asset.name} is not a JPEG file.`);
+  if (ext === 'ttf' && !starts([0, 1, 0, 0]) && !starts([116, 114, 117, 101])) throw new Error(`${asset.name} is not a TrueType font.`);
+  if (ext === 'otf' && !starts([79, 84, 84, 79])) throw new Error(`${asset.name} is not an OpenType font.`);
+  if (ext === 'svg' && !/<svg(?:\s|\/?>)/i.test(text(bytes, asset.name))) throw new Error(`${asset.name} is not an SVG file.`);
+  if (ext === 'txt') text(bytes, asset.name);
+}
+
+export function validateAssets(assets = []) {
+  if (!Array.isArray(assets) || assets.length > limits.count) throw new Error('This playground accepts up to 16 local assets.');
+  let size = 0;
+  const names = new Set();
+  for (const asset of assets) {
+    validateAsset(asset);
+    const key = assetKey(asset.name);
+    if (names.has(key)) throw new Error(`An asset named ${asset.name} is already present. Remove it before adding its replacement.`);
+    names.add(key);
+    size += asset.bytes.length;
+  }
+  if (size > limits.assets) throw new Error('Local assets must total no more than 20 MiB.');
+  return assets;
+}
+
+export function validateSource(html, css) {
+  if (typeof html !== 'string' || typeof css !== 'string' || encoder.encode(html + css).length > limits.source) {
+    throw new Error('This playground accepts up to 200 KB of HTML and CSS combined.');
+  }
+}
+
+// Validate the entire selection before the UI changes any source or asset state.
+export async function readSelection(files, currentAssets = []) {
+  if (!files.length || files.length > limits.count + 2) throw new Error('Choose one HTML file, one CSS file, and up to 16 assets.');
+  const selected = [];
+  let html = null, css = null;
+  let assetCount = currentAssets.length, assetBytes = currentAssets.reduce((sum, asset) => sum + asset.bytes.length, 0);
+  const sourceTypes = new Set();
+  for (const file of files) {
+    const ext = validateName(file.name);
+    const kind = ext === 'htm' ? 'html' : ext;
+    if (!sourceExtensions.has(ext) && !assetExtensions.has(ext)) throw new Error(`Unsupported file: ${file.name}`);
+    const cap = sourceExtensions.has(ext) ? limits.source : limits.file;
+    if (!Number.isSafeInteger(file.size) || file.size < 0 || file.size > cap) {
+      throw new Error(`${file.name} exceeds the ${sourceExtensions.has(ext) ? '200 KB source' : '8 MiB asset'} limit.`);
+    }
+    if (sourceExtensions.has(ext)) {
+      if (sourceTypes.has(kind)) throw new Error('Choose at most one HTML file and one CSS file at a time.');
+      sourceTypes.add(kind);
+    } else {
+      assetCount++;
+      assetBytes += file.size;
+    }
+    selected.push({ file, kind });
+  }
+  if (assetCount > limits.count) throw new Error('This playground accepts up to 16 local assets.');
+  if (assetBytes > limits.assets) throw new Error('Local assets must total no more than 20 MiB.');
+  const added = [];
+  for (const { file, kind } of selected) {
+    const bytes = new Uint8Array(await file.arrayBuffer());
+    if (bytes.length !== file.size) throw new Error(`Could not read all of ${file.name}. Choose the file again.`);
+    if (kind === 'html') html = text(bytes, file.name);
+    else if (kind === 'css') css = text(bytes, file.name);
+    else added.push({ name: file.name, bytes });
+  }
+  validateAssets([...currentAssets, ...added]);
+  return { html, css, assets: added };
+}

docs/assets/playground/playground.css

@@ -3,7 +3,8 @@ import { storeZip } from './zip-store.js';
 
 const encoder = new TextEncoder();
 const decoder = new TextDecoder();
-const examples = new Set(['invoice', 'report', 'notice']);
+const examples = new Set(['invoice', 'report', 'notice', 'custom']);
+const { validateAssets, isFont } = await import(`./local-files.js${new URL(import.meta.url).search}`);
 
 async function fetchBytes(path) {
   let response;
@@ -20,11 +21,14 @@ async function sha256(bytes) {
   return Array.from(new Uint8Array(digest), value => value.toString(16).padStart(2, '0')).join('');
 }
 
-export async function buildProject({ name, html, css, language = 'python' }, load = fetchBytes) {
+export async function buildProject({ name, html, css, language = 'python', assets = [] }, load = fetchBytes) {
   if (!examples.has(name) || typeof html !== 'string' || typeof css !== 'string') {
     throw new Error('Choose a playground example before downloading a project.');
   }
   if (!['python', 'node'].includes(language)) throw new Error('Choose Python or Node.js for your project.');
+  validateAssets(assets);
+  // Snapshot before awaiting downloads so callers can keep editing their document.
+  assets = assets.map(asset => ({ name: asset.name, bytes: asset.bytes.slice() }));
   const node = language === 'node';
   const [buildBytes, fontBytes, runner, readme, license] = await Promise.all([
     load('build.json'), load('font-sources.json'), load(node ? 'project/node/render.mjs' : 'project/render.py'),
@@ -64,13 +68,15 @@ export async function buildProject({ name, html, css, language = 'python' }, loa
     { name: 'LICENSE.txt', bytes: license },
     { name: 'fonts/font-sources.json', bytes: fontBytes },
     ...fonts,
+    ...assets.map(asset => ({ name: `assets/${asset.name}`, bytes: asset.bytes })),
   ];
   const manifest = {
     format: 1, source: 'https://docs.fullbleed.dev/playground/', example: name,
     engine: { name: 'fullbleed', version },
     files: await Promise.all(files.map(async file => ({ path: file.name, bytes: file.bytes.length, sha256: await sha256(file.bytes) }))),
   };
   if (node) manifest.runtime = { name: 'node', minimumVersion: '22', package: { name: 'fullbleed', version: packageVersion } };
+  if (assets.length) manifest.localAssets = assets.map(asset => ({ path: `assets/${asset.name}`, font: isFont(asset.name) }));
   files.push({ name: 'project.json', bytes: encoder.encode(JSON.stringify(manifest, null, 2) + '\n') });
   return storeZip(files);
 }

docs/assets/playground/project-export.js

@@ -1,7 +1,7 @@
 YOUR FULLBLEED PROJECT
 
 This ZIP contains the HTML and CSS that were in the playground when you clicked
-Download project, the bundled fonts and licenses, and a Python renderer.
+Download project, the bundled fonts and licenses, selected local assets, and a Python renderer.
 
 RUN IT
 
@@ -17,8 +17,10 @@ Edit input.html or style.css, then run python render.py again.
 The requirement pins Fullbleed {{ENGINE_VERSION}}, matching the browser demo.
 Installing it needs an internet connection. Rendering with these bundled assets
 runs locally; your HTML and CSS are not uploaded. No browser or system fonts are
-needed by this Python project. Additional assets you reference must be supplied
-separately. The local package can handle jobs beyond the browser demo's limits.
+needed by this Python project. Files you selected in the playground are in assets/;
+reference them with paths such as assets/logo.png. Selected TTF/OTF fonts are
+registered by the runner. Other assets you reference must be supplied separately.
+The local package can handle jobs beyond the browser demo's limits.
 
 KEEP BUILDING
 
@@ -38,3 +40,5 @@ LICENSES
 Starter templates and render.py: MIT (LICENSE.txt).
 Fonts: SIL Open Font License 1.1 (the *-OFL.txt files in fonts/).
 Font attribution and exact source revisions: fonts/font-sources.json.
+Imported documents and assets keep their original licenses. Selected TXT license
+files are preserved in assets/. The starter's MIT license does not relicense them.