TFQ0
diff --git a/‎README.md‎
Lines changed: 80 additions & 93 deletions b/‎README.md‎
Lines changed: 80 additions & 93 deletions
diff --git a/‎SETUP.md‎
Lines changed: 5 additions & 5 deletions b/‎SETUP.md‎
Lines changed: 5 additions & 5 deletions
@@ -1,137 +1,124 @@
 # Animated GitHub Profile Studio
 
-A browser-based editor for creating a personal GitHub profile README from one reusable configuration. Customize the design, fonts, text, animated terminal, featured repositories, images, GIFs, links, section order, colors, and motion settings, then export a ready-to-upload ZIP.
+A desktop-only visual editor for building animated GitHub profile READMEs from one reusable configuration. Design the profile, preview every theme and motion mode, then export a complete repository-ready bundle.
 
-The built-in sample is intentionally fictional and fully replaceable, so no maintainer profile, repository, or personal identity is used as the starting point.
+<p align="center">
+  <img src="./assets/profile-header-dark.svg" alt="Fictional desktop GitHub profile generated by Animated GitHub Profile Studio" width="100%">
+</p>
 
-After GitHub Pages is enabled, the hosted Studio is available at:
+<p align="center">
+  <a href="https://tfq0.github.io/animated-github-profile/"><strong>Open the hosted Studio</strong></a>
+  ·
+  <a href="./SETUP.md">Setup and release guide</a>
+  ·
+  <a href="./USER_CONTENT_NOTICE.md">Content notice</a>
+</p>
 
-**[Open the hosted Studio](https://tfq0.github.io/animated-github-profile/)**
+The header above is a committed example generated by the Studio. Its identity, repositories, and links are intentionally fictional and safe to replace.
 
-## Templates, layout, and media customization
+## What the Studio does
 
-Configuration v3 provides seven templates: Quality Control, Classic Terminal, Retro Arcade, Anime HUD, Bento Grid, Signal Poster, and Custom Canvas. The templates use generic, original interface elements and include no franchise characters, logos, or copied artwork.
+Animated GitHub Profile Studio turns a validated `profile.config.json` into a polished profile README and four self-contained desktop SVG headers:
 
-The templates are more than palette swaps: they provide structurally distinct compositions that adapt independently to desktop and mobile output. Custom Canvas uses the same validated rendering system and offers constrained layout controls rather than unrestricted canvas editing.
+- Dark animated
+- Light animated
+- Dark static
+- Light static
 
-The customization contract includes:
+Every header uses a fixed 1200 × 610 desktop canvas. The editor targets browser widths of 1180 px or wider and does not generate a separate phone layout.
 
-- Responsive composition, alignment, spacing, and placement choices within safe layout bounds.
-- Two to six workflow steps, with an allowlisted safe shape selected for each step.
-- Decorative shapes described through a bounded SVG-safe DSL. The renderer converts validated shape data into SVG; users cannot insert arbitrary SVG elements or path commands.
-- Curated font presets that map to controlled, SVG-safe system font stacks.
-- Structured remote media entries for images and GIFs referenced by HTTPS URL, with accessibility and attribution information kept alongside each entry. Media remains separate README content and is not inserted into the generated hero canvas.
+## Highlights
 
-Applying a template changes its visual system and layout defaults without replacing the user's profile text, repositories, links, sections, or media. Loading a complete sample is a separate, confirmed action that replaces profile content. Valid v1 and v2 configurations migrate automatically when imported or restored from browser storage.
-
-The editor does not accept arbitrary raw CSS, SVG markup, SVG paths, or remote fonts. Decorative elements are code-generated from allowlisted primitives and bounded numeric values.
-
-## What it includes
-
-- Live desktop and mobile preview in dark and light themes.
-- Animated and reduced-motion/static SVG variants.
-- Seven structurally distinct responsive templates plus constrained custom layout controls.
-- Design, font, profile, hero, workflow-step shape, decorative shape, project, skill, link, structured media, palette, section, Markdown, and footer editing.
-- Optional public GitHub repository import with no login or token.
+- Seven distinct designs: Quality Control, Classic Terminal, Retro Arcade, Anime HUD, Bento Grid, Signal Poster, and Custom Canvas.
+- Live GitHub-style preview with dark/light and animated/static controls.
+- Editable identity, headline, terminal sequence, workflow, projects, skills, links, media, sections, colors, typography, and footer.
+- Constrained composition, spacing, alignment, panel, workflow, and decorative-shape controls.
+- Optional import of public GitHub repository metadata without login or a token.
 - Local autosave of the last valid configuration.
-- Versioned `profile.config.json` import/export.
-- One-click download of the currently previewed SVG variant without creating a ZIP.
-- Deterministic ZIP generation containing `README.md`, setup guidance, the saved config, and all eight SVG assets.
-- Strict runtime validation, HTTPS-only generated links, contextual XML/Markdown escaping, and self-contained SVG output.
-- WebMCP tools for agents to read or stage the same configuration used by the visible editor.
+- Versioned configuration import/export with automatic v1 and v2 migration.
+- Direct download of the currently previewed SVG.
+- Deterministic ZIP export containing everything needed for a profile repository.
+- Reduced-motion fallbacks and dark/light theme selection in the generated README.
+- Agent access through WebMCP tools that read or stage the same configuration used by the editor.
 
-## Use the studio
+## Create a profile
 
-1. Open the app and choose one of the seven templates, then adjust its constrained layout controls if desired.
-2. Select **Start a blank profile** or customize the clearly labeled fictional sample.
-3. Work through Profile, Hero, workflow steps and shapes, Projects, Skills, Links, Media, Colors, and Sections.
-4. Check the desktop/mobile, dark/light, and animated/static previews. Responsive compositions can adapt between desktop and mobile rather than preserving identical coordinates.
-5. Resolve validation errors and review any design warnings in Export.
-6. To keep only the image, choose its desktop/mobile, dark/light, and animated/static options, then select **Download SVG**.
-7. To publish the complete profile, download the ZIP instead.
-8. Upload its `README.md` and `assets/` directory to the public GitHub repository whose name exactly matches your username.
+1. Open the [hosted Studio](https://tfq0.github.io/animated-github-profile/) or run it locally.
+2. Choose a design, start with a blank profile, or load the clearly labeled fictional sample.
+3. Customize the profile content and desktop composition.
+4. Review the dark/light and animated/static previews.
+5. Resolve validation errors and inspect any design warnings in the Export step.
+6. Select **Save SVG** for one header or **Download ZIP** for the complete profile.
+7. Upload the generated `README.md` and `assets/` directory to the public GitHub repository named exactly like your username.
 
-Keep the exported `profile.config.json`; importing it later restores an editable profile instead of requiring manual SVG changes.
+Keep the exported `profile.config.json`. Importing it later restores the editable profile without requiring manual SVG changes.
 
-## Deploy the Studio with GitHub Pages
+## Exported bundle
 
-This repository includes [`.github/workflows/deploy-pages.yml`](./.github/workflows/deploy-pages.yml). The workflow runs the type-checker and tests, builds the Vite application with the repository's GitHub Pages base path, and publishes the generated `dist/` directory whenever a commit is pushed to `main`. A failed check stops the deployment.
+| File | Purpose |
+| :--- | :--- |
+| `README.md` | Generated GitHub profile content and theme/motion image selection |
+| `profile.config.json` | Reusable, editable source configuration |
+| `SETUP.md` | Profile-specific publishing instructions |
+| `assets/profile-header-dark.svg` | Dark animated desktop header |
+| `assets/profile-header-light.svg` | Light animated desktop header |
+| `assets/profile-header-dark-static.svg` | Dark reduced-motion desktop header |
+| `assets/profile-header-light-static.svg` | Light reduced-motion desktop header |
 
-Complete this one-time setup after pushing the repository to GitHub:
+Structured remote media remains referenced by HTTPS URL. It is not copied into the ZIP or embedded in the generated header.
 
-1. Open the repository on GitHub.
-2. Select **Settings**, then **Pages**.
-3. Under **Build and deployment**, choose **GitHub Actions** as the source.
-4. Open the **Actions** tab and run **Deploy to GitHub Pages**, or push another commit to `main`.
-5. Wait for the workflow to finish, then open `https://tfq0.github.io/animated-github-profile/`.
+## Customization model
 
-No deployment branch, generated `dist/` commit, server, API key, or repository secret is required. The published Studio is a public static website and stores editable drafts in each visitor's browser.
+`ProfileConfig` is the single source of truth for the editor, preview, README, SVGs, saved draft, and ZIP.
 
-The `animated-github-profile` repository publishes the Studio itself. It is separate from a generated profile repository named `<username>/<username>`: use **Download complete ZIP** inside the Studio when you want to publish a generated profile.
+| Area | Available controls |
+| :--- | :--- |
+| Design | Template, composition, content order, spacing, panel system, background pattern, console style, text alignment |
+| Hero | Headline, command, status checks, animation timing, workflow labels and shapes, footer labels |
+| Content | About text, repositories, skills, links, custom Markdown, structured images and GIFs |
+| Appearance | Curated system font stacks, dark/light palettes, corner radius, decorative shapes |
+| Output | Theme, motion mode, standalone SVG, full ZIP, configuration import/export |
 
-To publish a later update, verify it locally and push it to `main`. GitHub Actions will replace the hosted version automatically:
-
-```bash
-npm run typecheck
-npm test
-npm run build
-git push origin main
-```
+Applying a design changes the visual system without replacing profile content. Loading a complete sample is a separate confirmed action because it replaces the current content.
 
 ## Local development
 
-Requirements: Node.js `^22.13.0` or `>=24.0.0` and npm.
+Requirements:
+
+- Node.js `^22.13.0` or `>=24.0.0`
+- npm
+
+Install dependencies and start the development server:
 
 ```bash
 npm ci
 npm run dev
 ```
 
-The local app is served at `http://localhost:4173/`.
+Open `http://localhost:4173/` in a desktop browser.
+
+Run the complete verification pipeline:
 
 ```bash
 npm run typecheck
 npm test
 npm run build
 ```
 
-The production site is written to `dist/`. Local builds keep portable relative asset URLs; the Pages workflow supplies the repository path during its production build.
-
 ## Architecture
 
 ```text
 src/
-├── domain/profile.ts       # strict v3 config plus v1/v2 migration
-├── domain/presets.ts       # trusted template defaults and visual presets
+├── domain/
+│   ├── profile.ts       # strict v3 schema, defaults, and v1/v2 migration
+│   └── presets.ts       # trusted visual presets
 ├── generator/
-│   ├── svg.ts              # pure eight-variant SVG renderer
-│   ├── readme.ts           # GitHub README renderer
-│   ├── escape.ts           # XML/Markdown/URL safety boundaries
-│   └── artifacts.ts        # deterministic file and ZIP assembly
-├── services/github.ts      # optional public repository import
-├── components/             # editor fields and GitHub-like preview
-├── webmcp.ts               # agent-facing read/stage actions
-└── App.tsx                 # editor state and workflows
+│   ├── svg.ts           # four-variant desktop SVG renderer
+│   ├── readme.ts        # GitHub README renderer
+│   ├── escape.ts        # XML, Markdown, and URL safety boundaries
+│   └── artifacts.ts     # deterministic file and ZIP assembly
+├── services/github.ts   # optional public repository import
+├── components/          # editor fields and profile preview
+├── webmcp.ts            # agent-facing read and stage tools
+└── App.tsx              # editor state and workflows
 ```
-
-`ProfileConfig` is the single source of truth. The visible preview, README source, SVG files, saved config, and ZIP are all produced from the same validated object. Template, responsive layout, workflow-shape, and decorative-shape values are resolved through trusted renderer registries. Imported GitHub data becomes an editable snapshot; it is never a hidden dependency of later exports.
-
-## Privacy and output safety
-
-- The editor has no backend and requests no GitHub token.
-- Drafts and the short-lived public repository cache stay in browser storage.
-- Only public repository metadata is fetched directly from GitHub's public API.
-- Generated SVGs contain no scripts, event handlers, remote fonts, external images, tracking, or live CI claims.
-- Layout and decorative SVG output is generated only from validated, bounded controls and allowlisted shape primitives; raw CSS, SVG markup, and path data are not accepted.
-- User-selected media is referenced by HTTPS URL in the README rather than copied into the ZIP or embedded in the generated hero SVG.
-- Previewing or viewing remote media may send an ordinary request to its third-party host. Remote content can disappear or change independently of the Studio.
-- Static fallbacks are generated for visitors who prefer reduced motion.
-- Custom Markdown blocks raw HTML and neutralizes non-HTTPS link destinations in generated output.
-
-Users must own or hold permission for any media they add. Attribution alone does not grant permission, and adding media does not imply affiliation with or endorsement by its creator or rights holder. See [User content and third-party media notice](./USER_CONTENT_NOTICE.md).
-
-## License
-
-Animated GitHub Profile Studio is released under the [MIT License](./LICENSE).
-
-The MIT License does not grant rights to user-supplied content or third-party media. See [User content and third-party media notice](./USER_CONTENT_NOTICE.md).
@@ -19,26 +19,26 @@ npm test
 npm run build
 ```
 
-These checks cover TypeScript, strict config parsing, all eight SVG variants, reduced-motion output, README-to-asset references, deterministic ZIP contents, unsafe input handling, public GitHub import errors, cache validation, and the WebMCP contract.
+These checks cover TypeScript, strict config parsing, all four desktop SVG variants, reduced-motion output, README-to-asset references, deterministic ZIP contents, unsafe input handling, public GitHub import errors, cache validation, and the WebMCP contract.
 
 The v3 verification matrix must also cover:
 
 - Quality Control, Classic Terminal, Retro Arcade, Anime HUD, Bento Grid, Signal Poster, and Custom Canvas.
-- Every supported responsive composition in desktop and mobile output, including constrained alignment, spacing, and placement boundary values.
+- Every supported desktop composition, including constrained alignment, spacing, and placement boundary values.
 - Two-step and six-step workflows, every allowlisted per-step shape, ordering, and text-fit limits.
 - Decorative shapes at their count and numeric boundaries, plus rejection of unknown primitives, excessive values, raw SVG, arbitrary path data, and CSS injection.
 - Every curated font preset and rejection of arbitrary font-family values or remote font references.
 - Migration of valid v1 and v2 drafts to v3, with user content and existing visual choices preserved.
 - Structured remote-media validation and attribution, rejection of unsafe media URLs, and confirmation that media remains separate HTTPS README content rather than hero SVG content.
 - Preservation of profile text, repositories, links, sections, and media when applying a template. Loading a complete sample must remain a separate confirmed replacement action.
 
-For a release, inspect all seven templates with representative and maximum-length content in desktop/mobile, dark/light, and animated/static previews. Confirm that compositions are visibly distinct, remain within the SVG viewBox, and adapt safely between desktop and mobile. Design warnings are advisory because fixed SVG artwork cannot measure browser font metrics during generation.
+For a release, inspect all seven templates with representative and maximum-length content in the desktop dark/light and animated/static previews. Confirm that compositions are visibly distinct and remain within the 1200×610 SVG viewBox. Design warnings are advisory because fixed SVG artwork cannot measure browser font metrics during generation.
 
 Exercise the constrained custom layout controls at minimum and maximum values, then verify that the visible preview, downloaded current SVG, and matching ZIP asset render the same configuration. Check workflows with two and six steps and mix every safe step shape. Decorative-shape tests must confirm that generated primitives remain bounded and cannot obscure required text or controls.
 
-The preview toolbar can download its currently selected SVG by itself. Use the Export panel's complete ZIP when publishing the full README and all responsive theme variants.
+The preview toolbar can download its currently selected SVG by itself. Use the Export panel's complete ZIP when publishing the full README and all desktop theme and motion variants.
 
-When changing the editor layout, inspect 1440 px, 1180 px, 900 px, 620 px, and 320 px viewport widths. Confirm that navigation and export actions remain reachable, keyboard focus remains visible, remote media stays within the preview, and no horizontal page overflow is introduced.
+When changing the editor layout, inspect the supported desktop widths at 1440 px and 1180 px. Confirm that navigation and export actions remain reachable, keyboard focus remains visible, remote media stays within the preview, and no horizontal page overflow is introduced.
 
 Custom Canvas is constrained despite its name. Do not add arbitrary raw CSS, SVG markup, SVG path input, or remote fonts. Layouts, workflow shapes, and decorative shapes must be selected or composed through validated controls and code-generated renderer primitives.