npm - @baaqar/artifact-to-pwa - Versions diffs - 1.0.0 - Mend

@baaqar/artifact-to-pwa 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/README.md ADDED Viewed

@@ -0,0 +1,79 @@
+# artifact-to-pwa
+> Convert any Claude artifact (HTML / React / JSX) or public URL into an installable Progressive Web App — no build step, no Android Studio, no Xcode.
+## Usage
+```bash
+# From a local file
+npx artifact-to-pwa ./my-app.jsx
+# From a published Claude artifact URL
+npx artifact-to-pwa https://claude.site/artifacts/abc123
+# With options
+npx artifact-to-pwa ./app.html --name "My Tool" --color "#ff6b6b" --out ./dist
+```
+## Options
+| Flag | Description | Default |
+|------|-------------|---------|
+| `-n, --name <name>` | App name | Derived from filename / URL |
+| `-s, --short-name <name>` | Home screen label (max ~12 chars) | First 12 chars of name |
+| `-d, --description <text>` | App description | |
+| `-c, --color <hex>` | Theme / accent color | `#6366f1` |
+| `-b, --bg <hex>` | Splash background color | `#ffffff` |
+| `-o, --out <dir>` | Output directory | `./<slug>-pwa` |
+## What it generates
+```
+my-app-pwa/
+├── index.html    ← your app, PWA-ready
+├── manifest.json ← name, icon, colors, display mode
+├── sw.js         ← service worker (offline support)
+├── icon.svg      ← auto-generated app icon
+└── README.md     ← install instructions
+```
+## How to install the PWA
+### Desktop / Android (Chrome or Edge)
+```bash
+npx serve my-app-pwa
+```
+Open the URL → click the **Install** icon in the address bar.
+### iPhone / iPad (Safari)
+Deploy the folder anywhere static (see below), open in Safari → **Share** → **Add to Home Screen**.
+### One-click deploy options
+| Host | Command |
+|------|---------|
+| **Netlify** | Drag the folder to [netlify.com/drop](https://netlify.com/drop) |
+| **Vercel** | `npx vercel my-app-pwa` |
+| **GitHub Pages** | Push folder contents, enable Pages in repo settings |
+## Supported source formats
+| Format | Detection |
+|--------|-----------|
+| Full HTML document | `<!DOCTYPE html>` or `<html>` present |
+| HTML fragment | Partial markup without doctype |
+| React / JSX | `import React`, `useState`, `export default function`, JSX syntax |
+| Public URL | Embedded as a full-screen iframe |
+React artifacts are served using Babel standalone + CDN React — **no bundler needed**.
+## Why PWA instead of APK?
+- **Zero build tooling** — no Android Studio, no Xcode, no Java
+- **Cross-platform** — installs on Android, iOS, Windows, macOS, Linux
+- **Always up to date** — users get the latest version automatically
+- **Offline support** — built-in service worker caches assets
+---
+Made with ❤️ to keep Claude artifacts alive outside the chat.

package/bin/cli.js ADDED Viewed

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import { program } from 'commander';
+import { generatePWA } from '../src/generator.js';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { join, dirname } from 'path';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf8'));
+program
+  .name('artifact-to-pwa')
+  .description(
+    'Convert a Claude artifact (HTML/React/JSX) or any public URL into a ready-to-install PWA.\n\n' +
+    'Examples:\n' +
+    '  npx artifact-to-pwa ./my-app.jsx\n' +
+    '  npx artifact-to-pwa https://claude.site/artifacts/abc123\n' +
+    '  npx artifact-to-pwa ./app.html --name "My Tool" --color "#ff6b6b"'
+  )
+  .version(pkg.version)
+  .argument('<source>', 'Local file path (.html, .jsx, .js) or public URL')
+  .option('-n, --name <name>',        'App name (default: derived from filename or URL)')
+  .option('-s, --short-name <name>',  'Short name shown on home screen (default: first 12 chars of name)')
+  .option('-d, --description <text>', 'App description', '')
+  .option('-c, --color <hex>',        'Theme / accent color',    '#6366f1')
+  .option('-b, --bg <hex>',           'Splash screen background color', '#ffffff')
+  .option('-o, --out <dir>',          'Output directory (default: ./<slug>-pwa)')
+  .action(generatePWA);
+program.parse();

package/package.json ADDED Viewed

@@ -0,0 +1,33 @@
+{
+  "name": "@baaqar/artifact-to-pwa",
+  "version": "1.0.0",
+  "description": "Convert any Claude artifact (HTML/React/JSX) or public URL into an installable PWA — no build step required",
+  "type": "module",
+  "bin": {
+    "artifact-to-pwa": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md"
+  ],
+  "keywords": [
+    "pwa",
+    "progressive-web-app",
+    "claude",
+    "artifact",
+    "installable",
+    "offline",
+    "cli",
+    "converter"
+  ],
+  "author": "",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0"
+  }
+}

package/src/detect.js ADDED Viewed

@@ -0,0 +1,146 @@
+/**
+ * Detects whether a string of source code is:
+ *   "full-html"     — a complete <!DOCTYPE html> document
+ *   "html-fragment" — partial HTML without doctype/html tags
+ *   "react"         — JSX / React component
+ */
+export function detectCodeType(code) {
+  const t = code.trim();
+  if (/^<!DOCTYPE\s+html/i.test(t) || /^<html[\s>]/i.test(t)) {
+    return 'full-html';
+  }
+  const reactSignals = [
+    /from ['"]react['"]/,
+    /import\s+React/,
+    /export\s+default\s+function/,
+    /export\s+default\s+class/,
+    /useState\s*[(<]/,
+    /useEffect\s*\(/,
+    /React\.createElement/,
+    /return\s*\(\s*</,
+    /=>\s*\(/,        // arrow fn returning JSX
+    /<>\s*</,         // fragment shorthand
+  ];
+  if (reactSignals.some(re => re.test(t))) return 'react';
+  // Looks like it starts with an HTML tag but has no doctype
+  if (/^<[a-zA-Z]/.test(t)) return 'html-fragment';
+  // Default: treat as an HTML fragment
+  return 'html-fragment';
+}
+/**
+ * Wraps source code into a complete, PWA-ready index.html.
+ * Injects manifest link, theme-color meta, and SW registration.
+ */
+export function wrapCode(code, { appName, themeColor }) {
+  const type = detectCodeType(code);
+  const headInjects = `
+  <meta name="theme-color" content="${themeColor}">
+  <meta name="apple-mobile-web-app-capable" content="yes">
+  <meta name="apple-mobile-web-app-status-bar-style" content="default">
+  <meta name="apple-mobile-web-app-title" content="${appName}">
+  <link rel="apple-touch-icon" href="icon.svg">
+  <link rel="manifest" href="manifest.json">`.trim();
+  const swScript = `
+<script>
+  if ('serviceWorker' in navigator) {
+    window.addEventListener('load', () =>
+      navigator.serviceWorker.register('sw.js').catch(() => {})
+    );
+  }
+</script>`.trim();
+  // ── Full HTML document ────────────────────────────────────────────────────
+  if (type === 'full-html') {
+    let result = code;
+    // Inject into existing <head>
+    if (/<\/head>/i.test(result)) {
+      result = result.replace(/<\/head>/i, `  ${headInjects}\n</head>`);
+    } else {
+      // No </head>: inject after <html> or at top
+      result = result.replace(/(<html[^>]*>)/i, `$1\n<head>\n  ${headInjects}\n</head>`);
+    }
+    // Inject SW before </body>
+    if (/<\/body>/i.test(result)) {
+      result = result.replace(/<\/body>/i, `  ${swScript}\n</body>`);
+    } else {
+      result += `\n${swScript}`;
+    }
+    return result;
+  }
+  // ── React / JSX ───────────────────────────────────────────────────────────
+  if (type === 'react') {
+    // Strip top-level React imports (provided by CDN)
+    let cleaned = code
+      .replace(/^import\s+React[^;]*;\s*/gm, '')
+      .replace(/^import\s*\{[^}]+\}\s*from\s*['"]react['"];\s*/gm, '')
+      .trim();
+    // Normalize export default → __App
+    cleaned = cleaned
+      .replace(/^export\s+default\s+function\s+(\w+)/, 'function __App')
+      .replace(/^export\s+default\s+class\s+(\w+)/, 'class __App')
+      .replace(/^export\s+default\s+/, 'const __App = ');
+    const hasApp = /\b__App\b/.test(cleaned);
+    const renderLine = hasApp
+      ? `ReactDOM.createRoot(document.getElementById('root')).render(React.createElement(__App));`
+      : `/* Could not auto-detect root component — update the render call below */`;
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${appName}</title>
+  ${headInjects}
+  <!-- React + Babel (no build step) -->
+  <script src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
+  <script src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
+  <script src="https://unpkg.com/@babel/standalone/babel.min.js"></script>
+  <script src="https://cdn.tailwindcss.com"></script>
+  <style>html,body,#root{height:100%;margin:0;padding:0;}</style>
+  ${swScript}
+</head>
+<body>
+  <div id="root"></div>
+  <script type="text/babel">
+const {
+  useState, useEffect, useRef, useCallback,
+  useMemo, useReducer, useContext, createContext
+} = React;
+${cleaned}
+${renderLine}
+  </script>
+</body>
+</html>`;
+  }
+  // ── HTML fragment ─────────────────────────────────────────────────────────
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${appName}</title>
+  ${headInjects}
+  ${swScript}
+</head>
+<body>
+${code}
+</body>
+</html>`;
+}

package/src/generator.js ADDED Viewed

@@ -0,0 +1,123 @@
+import { mkdirSync, writeFileSync, readFileSync, existsSync } from 'fs';
+import { join, basename, extname } from 'path';
+import { detectCodeType }                              from './detect.js';
+import { generateSVGIcon }                             from './icons.js';
+import { buildIndexHTML, buildManifest, buildServiceWorker, buildReadme } from './templates.js';
+// ── Helpers ───────────────────────────────────────────────────────────────────
+const isURL = s => /^https?:\/\//i.test(s.trim());
+/** Turn an arbitrary string into a lowercase URL slug. */
+const slugify = s =>
+  s.toLowerCase().replace(/\s+/g, '-').replace(/[^a-z0-9-]/g, '').replace(/-+/g, '-');
+/** Derive a human-readable app name from a path or URL. */
+function nameFromSource(source) {
+  if (isURL(source)) {
+    try {
+      const host = new URL(source).hostname.replace(/^www\./, '');
+      const part = host.split('.')[0];
+      return part.charAt(0).toUpperCase() + part.slice(1);
+    } catch {
+      return 'My App';
+    }
+  }
+  const base = basename(source, extname(source));
+  return base
+    .replace(/[-_]+/g, ' ')
+    .replace(/\b\w/g, c => c.toUpperCase());
+}
+// ── Main export ───────────────────────────────────────────────────────────────
+/**
+ * Orchestrates PWA generation from a CLI invocation.
+ *
+ * @param {string} source  - File path or URL
+ * @param {object} options - Commander option values
+ */
+export async function generatePWA(source, options) {
+  // ── Lazy-load chalk (ESM-only package) ──────────────────────────────────
+  const { default: chalk } = await import('chalk');
+  console.log('\n' + chalk.bold.cyan('  artifact-to-pwa') + chalk.gray(' — PWA generator\n'));
+  // ── Resolve config ──────────────────────────────────────────────────────
+  const appName   = (options.name || nameFromSource(source)).trim();
+  const shortName = (options.shortName || appName).slice(0, 12).trim();
+  const slug      = slugify(appName) || 'my-pwa';
+  const outDir    = options.out || `./${slug}-pwa`;
+  const themeColor = /^#[0-9a-f]{3,6}$/i.test(options.color || '') ? options.color : '#6366f1';
+  const bgColor    = /^#[0-9a-f]{3,6}$/i.test(options.bg    || '') ? options.bg    : '#ffffff';
+  // ── Print plan ──────────────────────────────────────────────────────────
+  console.log(chalk.gray('  App name  ') + chalk.white(appName));
+  console.log(chalk.gray('  Output    ') + chalk.white(outDir));
+  console.log(chalk.gray('  Color     ') + chalk.white(themeColor));
+  console.log(chalk.gray('  Source    ') + chalk.white(source));
+  console.log();
+  // ── Resolve source content ──────────────────────────────────────────────
+  let mode, code;
+  if (isURL(source)) {
+    mode = 'url';
+    code = null;
+    console.log(chalk.gray('  ↳ URL mode: artifact will be embedded via iframe'));
+    console.log(chalk.gray('    (For offline support, paste the source code instead)\n'));
+  } else {
+    if (!existsSync(source)) {
+      console.error(chalk.red(`\n  ✗ File not found: ${source}\n`));
+      process.exit(1);
+    }
+    mode = 'code';
+    code = readFileSync(source, 'utf8');
+    const detectedType = detectCodeType(code);
+    console.log(chalk.gray(`  ↳ Detected: `) + chalk.yellow(detectedType));
+    console.log();
+  }
+  // ── Build config object ─────────────────────────────────────────────────
+  const config = {
+    appName,
+    shortName,
+    description: options.description || '',
+    themeColor,
+    bgColor,
+    slug,
+    mode,
+    code,
+    url: source,
+  };
+  // ── Create output directory ─────────────────────────────────────────────
+  mkdirSync(outDir, { recursive: true });
+  // ── Write files ─────────────────────────────────────────────────────────
+  const files = [
+    ['index.html',    buildIndexHTML(config)],
+    ['manifest.json', buildManifest(config)],
+    ['sw.js',         buildServiceWorker(config)],
+    ['icon.svg',      generateSVGIcon(themeColor, appName[0] || 'A')],
+    ['README.md',     buildReadme(config)],
+  ];
+  for (const [filename, content] of files) {
+    writeFileSync(join(outDir, filename), content, 'utf8');
+    console.log(chalk.green('  ✓ ') + filename);
+  }
+  // ── Done ─────────────────────────────────────────────────────────────────
+  console.log(
+    '\n' +
+    chalk.bold.white('  All done!\n') +
+    chalk.gray('\n  Test locally:\n') +
+    chalk.white(`    npx serve ${outDir}\n`) +
+    chalk.gray('\n  Or drag ') +
+    chalk.white(`'${outDir}/'`) +
+    chalk.gray(' to ') +
+    chalk.cyan('netlify.com/drop') +
+    chalk.gray(' for instant hosting + mobile install.\n')
+  );
+}

package/src/icons.js ADDED Viewed

@@ -0,0 +1,49 @@
+/**
+ * Generates a rounded-square SVG icon suitable for PWA manifests.
+ * SVG icons are supported by all modern browsers and require no
+ * native image-processing dependencies.
+ *
+ * @param {string} color  - Background hex color, e.g. "#6366f1"
+ * @param {string} letter - Single character to display
+ * @returns {string} SVG markup
+ */
+export function generateSVGIcon(color, letter = '?') {
+  const char = String(letter).charAt(0).toUpperCase();
+  // Derive a slightly lighter tint for a subtle inner glow
+  const tint = lighten(color, 0.15);
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="512" height="512">
+  <defs>
+    <radialGradient id="bg" cx="40%" cy="35%" r="65%">
+      <stop offset="0%" stop-color="${tint}"/>
+      <stop offset="100%" stop-color="${color}"/>
+    </radialGradient>
+  </defs>
+  <!-- Rounded square background -->
+  <rect width="512" height="512" rx="112" ry="112" fill="url(#bg)"/>
+  <!-- Centred letter -->
+  <text
+    x="256" y="340"
+    font-family="system-ui, -apple-system, sans-serif"
+    font-weight="700"
+    font-size="280"
+    text-anchor="middle"
+    fill="rgba(255,255,255,0.95)"
+  >${char}</text>
+</svg>`;
+}
+/**
+ * Naively lightens a hex color by mixing it toward white.
+ * @param {string} hex   - e.g. "#6366f1"
+ * @param {number} ratio - 0..1, how much to lighten
+ */
+function lighten(hex, ratio) {
+  const clean = hex.replace('#', '');
+  const r = parseInt(clean.slice(0, 2), 16);
+  const g = parseInt(clean.slice(2, 4), 16);
+  const b = parseInt(clean.slice(4, 6), 16);
+  const mix = v => Math.round(v + (255 - v) * ratio);
+  return `#${[mix(r), mix(g), mix(b)].map(v => v.toString(16).padStart(2, '0')).join('')}`;
+}

package/src/templates.js ADDED Viewed

@@ -0,0 +1,175 @@
+import { wrapCode } from './detect.js';
+/**
+ * Builds the main index.html.
+ * In URL mode the artifact is embedded in a full-screen iframe.
+ * In code mode the source is compiled/wrapped via detect.js.
+ */
+export function buildIndexHTML(config) {
+  const { mode, code, url, appName, themeColor } = config;
+  const headInjects = `
+  <meta name="theme-color" content="${themeColor}">
+  <meta name="apple-mobile-web-app-capable" content="yes">
+  <meta name="apple-mobile-web-app-status-bar-style" content="default">
+  <meta name="apple-mobile-web-app-title" content="${appName}">
+  <link rel="apple-touch-icon" href="icon.svg">
+  <link rel="manifest" href="manifest.json">`.trim();
+  const swScript = `
+<script>
+  if ('serviceWorker' in navigator) {
+    window.addEventListener('load', () =>
+      navigator.serviceWorker.register('sw.js').catch(() => {})
+    );
+  }
+</script>`.trim();
+  if (mode === 'url') {
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${appName}</title>
+  ${headInjects}
+  <style>
+    *     { margin: 0; padding: 0; box-sizing: border-box; }
+    html,
+    body   { width: 100%; height: 100%; overflow: hidden; }
+    iframe { width: 100%; height: 100%; border: none; display: block; }
+  </style>
+  ${swScript}
+</head>
+<body>
+  <iframe
+    src="${url}"
+    allow="fullscreen; clipboard-write; clipboard-read"
+    sandbox="allow-scripts allow-same-origin allow-forms allow-popups allow-modals"
+  ></iframe>
+</body>
+</html>`;
+  }
+  return wrapCode(code, { appName, themeColor });
+}
+/**
+ * Builds a Web App Manifest (manifest.json).
+ */
+export function buildManifest({ appName, shortName, description, themeColor, bgColor }) {
+  const manifest = {
+    name: appName,
+    short_name: shortName || appName.slice(0, 12),
+    description: description || '',
+    start_url: './',
+    scope: './',
+    display: 'standalone',
+    orientation: 'any',
+    theme_color: themeColor,
+    background_color: bgColor,
+    icons: [
+      {
+        src: 'icon.svg',
+        sizes: 'any',
+        type: 'image/svg+xml',
+        purpose: 'any maskable',
+      },
+    ],
+  };
+  return JSON.stringify(manifest, null, 2);
+}
+/**
+ * Builds a network-first service worker with offline fallback.
+ */
+export function buildServiceWorker({ slug }) {
+  const CACHE = `${slug}-v1`;
+  return `// Service worker generated by artifact-to-pwa
+const CACHE  = '${CACHE}';
+const ASSETS = ['./', './index.html', './manifest.json', './icon.svg'];
+// ── Install: pre-cache core assets ───────────────────────────────────────────
+self.addEventListener('install', event => {
+  event.waitUntil(
+    caches.open(CACHE)
+      .then(cache => cache.addAll(ASSETS))
+      .catch(() => { /* non-fatal if assets are missing at install time */ })
+  );
+  self.skipWaiting();
+});
+// ── Activate: remove stale caches ────────────────────────────────────────────
+self.addEventListener('activate', event => {
+  event.waitUntil(
+    caches.keys().then(keys =>
+      Promise.all(
+        keys
+          .filter(key => key !== CACHE)
+          .map(key => caches.delete(key))
+      )
+    )
+  );
+  self.clients.claim();
+});
+// ── Fetch: network-first, cache fallback ─────────────────────────────────────
+self.addEventListener('fetch', event => {
+  if (event.request.method !== 'GET') return;
+  event.respondWith(
+    fetch(event.request)
+      .then(response => {
+        // Cache a copy of successful responses
+        if (response.ok) {
+          const clone = response.clone();
+          caches.open(CACHE).then(cache => cache.put(event.request, clone));
+        }
+        return response;
+      })
+      .catch(() => caches.match(event.request))
+  );
+});
+`;
+}
+/**
+ * Builds a README.md for the generated PWA project.
+ */
+export function buildReadme({ appName, slug }) {
+  return `# ${appName}
+> Generated by [artifact-to-pwa](https://github.com/yourusername/artifact-to-pwa)
+## Install
+### Quickest (local)
+\`\`\`bash
+npx serve .
+\`\`\`
+Open the printed URL in Chrome/Edge → click the **Install** icon in the address bar.
+### Android (Chrome)
+Deploy to any static host, then visit on Android → ⋮ → **Add to Home Screen**.
+### iPhone / iPad (Safari)
+Deploy → open in Safari → **Share** → **Add to Home Screen**.
+## One-click deploy
+| Host | Steps |
+|------|-------|
+| **Netlify** | Drag this folder to [netlify.com/drop](https://netlify.com/drop) |
+| **Vercel** | \`npx vercel .\` |
+| **GitHub Pages** | Push to a repo, enable Pages in Settings |
+## Files
+| File | Purpose |
+|------|---------|
+| \`index.html\` | App entry point |
+| \`manifest.json\` | PWA metadata (name, icons, colors) |
+| \`sw.js\` | Service worker — enables offline use |
+| \`icon.svg\` | App icon (scales to any size) |
+`;
+}