storeshot 0.1.0

package/docs/mockup-bundles.md

@@ -0,0 +1,104 @@
+# StoreShot mockup bundles
+
+A mockup bundle is a normal folder. StoreShot deliberately uses an inspectable
+manifest plus ordinary image files instead of a custom binary archive or a ZIP
+dependency.
+
+```text
+my-device-frames/
+├── storeshot-mockups.json
+├── LICENSE
+└── assets/
+    ├── iphone-front.svg
+    └── iphone-angle.webp
+```
+
+Choose the folder from **Import bundle** in the device-frame picker. StoreShot
+reads the manifest first, lets the user select individual mockups, and copies
+only the selected definitions, their referenced assets, and the license file
+into the current project's `mockup-bundles/<bundle-id>/` folder.
+
+## Manifest
+
+`storeshot-mockups.json` uses format version 1:
+
+```json
+{
+  "format": "storeshot-mockup-bundle",
+  "version": 1,
+  "id": "example-apple-frames",
+  "name": "Example Apple Frames",
+  "author": "Example Studio",
+  "license": {
+    "name": "MIT",
+    "url": "https://example.com/license",
+    "file": "LICENSE"
+  },
+  "source": {
+    "name": "example/frames",
+    "url": "https://example.com/frames",
+    "revision": "0123456789abcdef"
+  },
+  "mockups": [
+    {
+      "id": "iphone-front",
+      "groupId": "iphone-example",
+      "groupName": "iPhone Example",
+      "name": "iPhone Example",
+      "description": "Front · Black",
+      "platform": "iphone",
+      "style": "standard",
+      "frame": "assets/iphone-front.svg",
+      "width": 462,
+      "height": 978,
+      "screen": {
+        "kind": "rect",
+        "x": 11,
+        "y": 11,
+        "width": 440,
+        "height": 956,
+        "cornerRadius": 55
+      }
+    }
+  ]
+}
+```
+
+All identifiers use lowercase letters, numbers, and hyphens. Asset and license
+paths are relative to the bundle root and cannot contain parent-directory
+segments. Supported frame formats are SVG, PNG, JPEG, and WebP. `thumbnail` is
+optional and defaults to the frame asset.
+
+Installed mockup IDs are namespaced as `<bundle-id>/<mockup-id>`, so unrelated
+bundles can safely use the same local mockup names.
+
+## Screen geometry
+
+The usual `rect` geometry places the screenshot into an axis-aligned rounded
+rectangle before drawing the transparent frame above it.
+
+Perspective frames can use a normalized 3×3 homography:
+
+```json
+{
+  "kind": "projective",
+  "transform": [
+    [0.62, -0.08, 0.20],
+    [0.04, 0.73, 0.12],
+    [0.02, -0.01, 1]
+  ],
+  "sourceCornerRadius": { "x": 0.08, "y": 0.04 }
+}
+```
+
+The transform maps normalized screenshot coordinates `(u, v)` into normalized
+frame coordinates. This makes matrices independent of the source screenshot
+resolution while the frame's `width` and `height` define its output coordinate
+space.
+
+## Licensing
+
+Bundle authors should include a license file when redistribution is allowed and
+record the source URL and revision. StoreShot preserves that metadata when only
+a subset of a bundle is imported. Importing a bundle does not grant rights to
+its assets; users remain responsible for following the bundle's license.

package/docs/releasing.md

@@ -0,0 +1,155 @@
+# Releasing StoreShot
+
+StoreShot publishes stable releases to npm from GitHub Actions. A `vX.Y.Z` Git
+tag is the release trigger, and the tag must match the version in `package.json`.
+The workflow uses npm trusted publishing (OIDC), so the repository does not need
+an `NPM_TOKEN` secret.
+
+## One-time setup and first release
+
+The `storeshot` package does not exist on npm yet. npm only allows a trusted
+publisher to be configured after the package exists, so `0.1.0` must be
+published manually once.
+
+1. Create an account at [npmjs.com](https://www.npmjs.com/) if needed, verify
+   the account email address, and enable two-factor authentication for
+   authorization and publishing.
+2. Make sure the publishing-workflow and package-metadata changes are merged
+   into `main` and pushed to GitHub.
+3. From a clean checkout of `main`, sign in and verify the account:
+
+   ```bash
+   npm login
+   npm whoami
+   ```
+
+4. Validate exactly what will be released:
+
+   ```bash
+   npm ci
+   npm run check
+   npm pack --dry-run
+   ```
+
+   Read the package-content list. It should contain the built `dist/` files,
+   documentation, notices, and licenses, but no source-only secrets or local
+   project data.
+
+5. Publish the initial release:
+
+   ```bash
+   npm publish
+   ```
+
+   npm runs `prepublishOnly`, so the validation gate runs again before upload.
+   Complete the two-factor prompt when npm asks for it.
+
+6. Configure trusted publishing on the new package:
+
+   - Open the `storeshot` package on npm while signed in, then go to
+     **Settings** and find **Trusted Publisher**.
+   - Select **GitHub Actions**.
+   - Organization or user: `mikkokut`
+   - Repository: `storeshot`
+   - Workflow filename: `publish.yml`
+   - Environment: leave empty
+   - Allowed action: `npm publish`
+
+   The names are case-sensitive. Enter only `publish.yml`, not the full
+   `.github/workflows/publish.yml` path.
+
+7. Create and push the initial release tag. The workflow recognizes that
+   `0.1.0` already exists and exits successfully:
+
+   ```bash
+   git tag -a v0.1.0 -m "Release v0.1.0"
+   git push origin v0.1.0
+   ```
+
+8. Confirm that the **Publish to npm** workflow succeeded in GitHub Actions and
+   that `npm view storeshot version` prints `0.1.0`.
+
+After the first trusted publish succeeds, remove any old npm automation tokens.
+In the npm package settings, disallow token-based publishing if that option is
+available. Keep trusted publishing enabled.
+
+## Publishing later versions
+
+Prepare releases on `main`, after all intended changes have landed.
+
+1. Update `CHANGELOG.md`: move relevant entries from **Unreleased** into a new
+   version section with the release date, and restore an empty **Unreleased**
+   section for future work.
+2. Check the working tree and run the release gate:
+
+   ```bash
+   git status --short
+   npm ci
+   npm run check
+   npm pack --dry-run
+   ```
+
+3. Choose the semantic-version increment:
+
+   - `patch` for backward-compatible fixes (`0.1.0` to `0.1.1`)
+   - `minor` for backward-compatible features (`0.1.0` to `0.2.0`)
+   - `major` for breaking changes once the project reaches `1.0.0`
+   - While the project is on `0.x`, use a minor bump for meaningful breaking
+     changes and explain them in the changelog.
+
+4. Commit the changelog and other release preparation, then make sure the tree
+   is clean:
+
+   ```bash
+   git add CHANGELOG.md
+   git commit -m "Prepare v0.1.1 release"
+   git status --short
+   ```
+
+5. Let npm update both `package.json` and `package-lock.json`, create the version
+   commit, and create the matching Git tag:
+
+   ```bash
+   npm version patch -m "Release v%s"
+   ```
+
+   Replace `patch` with `minor`, `major`, or an exact version when appropriate.
+   Do not use `--force`; `npm version` intentionally requires a clean tree.
+
+6. Inspect the result before publishing:
+
+   ```bash
+   git show --stat --oneline HEAD
+   git tag --points-at HEAD
+   ```
+
+7. Push the version commit and tag together:
+
+   ```bash
+   git push origin main --follow-tags
+   ```
+
+8. Watch the **Publish to npm** workflow. When it succeeds, verify the registry:
+
+   ```bash
+   npm view storeshot version
+   npm install --global storeshot@0.1.1
+   storeshot --version
+   ```
+
+   Replace `0.1.1` with the released version. Optionally create a GitHub Release
+   from the same tag and copy the corresponding changelog section into it.
+
+## If publishing fails
+
+- Fix the cause; do not delete and recreate a published npm version. npm package
+  name/version pairs cannot be reused.
+- If validation fails before `npm publish`, fix the code on `main`, remove the
+  unpublished local and remote tag, bump again, and push the corrected tag.
+- If npm reports an authentication error, confirm that trusted publishing uses
+  `mikkokut/storeshot`, the exact filename `publish.yml`, no environment, and
+  that the workflow has `id-token: write` permission.
+- If npm already contains the version, the workflow exits successfully without
+  attempting to overwrite it.
+- Never add an npm write token to the repository or workflow. Trusted publishing
+  is the normal release path after the initial bootstrap release.

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "storeshot",
+  "version": "0.1.0",
+  "description": "A local-first, agent-native CLI for creating App Store screenshots.",
+  "keywords": [
+    "app-store",
+    "screenshots",
+    "ios",
+    "cli",
+    "local-first",
+    "agent-native"
+  ],
+  "license": "MIT",
+  "author": "Mikko Kutilainen",
+  "homepage": "https://github.com/mikkokut/storeshot#readme",
+  "bugs": {
+    "url": "https://github.com/mikkokut/storeshot/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mikkokut/storeshot.git"
+  },
+  "type": "module",
+  "bin": {
+    "storeshot": "./dist/cli.js"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "dist",
+    "docs",
+    "LICENSE",
+    "README.md",
+    "SECURITY.md",
+    "THIRD_PARTY_LICENSES.txt",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "scripts": {
+    "storeshot": "tsx src/cli.ts",
+    "dev": "tsx watch --clear-screen=false src/cli.ts dev playground --no-open",
+    "build": "npm run build:cli && npm run build:ui",
+    "build:cli": "tsup",
+    "build:ui": "vite build",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test test/*.test.ts",
+    "licenses": "node scripts/generate-third-party-licenses.mjs",
+    "check:licenses": "node scripts/generate-third-party-licenses.mjs --check",
+    "check": "npm run check:licenses && npm run typecheck && npm test && npm run build",
+    "prepublishOnly": "npm run check"
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "dependencies": {
+    "@base-ui/react": "^1.6.0",
+    "@fontsource-variable/geist": "^5.2.9",
+    "commander": "^15.0.0",
+    "fabric": "^7.4.0",
+    "open": "^11.0.0",
+    "react-resizable-panels": "^4.12.2",
+    "tw-animate-css": "^1.4.0"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.3.2",
+    "@types/node": "^26.1.1",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.3",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "lucide-react": "^1.24.0",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "shadcn": "^4.13.0",
+    "tailwind-merge": "^3.6.0",
+    "tailwindcss": "^4.3.2",
+    "tsup": "^8.5.1",
+    "tsx": "^4.23.1",
+    "typescript": "^7.0.2",
+    "vite": "^8.1.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}