proto-plugin 0.1.0

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "proto-plugin",
+  "version": "0.1.0",
+  "type": "module",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/maayanalbert/proto-plugin.git",
+    "directory": "packages/prototype"
+  },
+  "files": [
+    "src",
+    "scripts",
+    "README.md",
+    "AGENTS.md",
+    "components.json",
+    "tsconfig.json"
+  ],
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./config": "./src/config/define-prototype-config.ts",
+    "./config/prototype-icon": "./src/config/prototype-icon.tsx",
+    "./app": "./src/app.ts",
+    "./with-prototype": "./src/config/with-prototype.ts",
+    "./server": "./src/server.ts",
+    "./styles/globals.css": "./src/styles/globals.css"
+  },
+  "scripts": {
+    "verify:prototype-ids": "node scripts/verify-prototype-component-ids.mjs",
+    "verify:prototype-preview-states": "node scripts/verify-prototype-preview-states.mjs",
+    "link-source": "./scripts/link-source.sh",
+    "sync-from-source": "./scripts/sync-from-source.sh",
+    "link-source-db": "./scripts/link-source-db.sh",
+    "share-prototype": "./scripts/share-prototype.sh",
+    "download-mobbin-references": "node scripts/download-mobbin-reference-images.mjs",
+    "publish-package": "./scripts/publish-package.sh"
+  },
+  "peerDependencies": {
+    "next": ">=15",
+    "react": ">=19",
+    "react-dom": ">=19"
+  },
+  "dependencies": {
+    "@radix-ui/react-dialog": "^1.1.15",
+    "@radix-ui/react-dropdown-menu": "^2.1.16",
+    "@radix-ui/react-label": "^2.1.8",
+    "@radix-ui/react-scroll-area": "^1.2.10",
+    "@radix-ui/react-select": "^2.2.6",
+    "@radix-ui/react-separator": "^1.1.8",
+    "@radix-ui/react-slider": "^1.3.6",
+    "@radix-ui/react-slot": "^1.2.4",
+    "@radix-ui/react-switch": "^1.2.6",
+    "@radix-ui/react-tabs": "^1.1.13",
+    "@radix-ui/react-toggle-group": "^1.1.11",
+    "@radix-ui/react-tooltip": "^1.2.8",
+    "@upstash/redis": "^1.38.0",
+    "@vercel/blob": "^2.0.0",
+    "@vercel/kv": "^2.0.0",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.0",
+    "html-to-image": "^1.11.13",
+    "lucide-react": "^0.543.0",
+    "modern-screenshot": "^4.6.0",
+    "sass": "^1.86.0",
+    "server-only": "^0.0.1",
+    "sonner": "^1.7.4",
+    "tailwind-merge": "^2.5.2"
+  }
+}

package/scripts/download-mobbin-reference-images.mjs

@@ -0,0 +1,112 @@
+/**
+ * Fetches full-resolution (1920w) Mobbin screen images for prototype references.
+ * MCP short URLs are ~768px — too small for the overview modal grid.
+ *
+ * Usage:
+ *   pnpm download-mobbin-references -- --ids=id1,id2,id3
+ *   pnpm download-mobbin-references -- --config=path/to/ids.json
+ *
+ * Config JSON shape: { "screenIds": ["uuid", ...] }
+ */
+
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import {
+  resolveHostRoot,
+  resolveToolRoot,
+} from "./lib/resolve-host-root.mjs";
+
+const toolRoot = resolveToolRoot(import.meta.url);
+const hostRoot = resolveHostRoot(toolRoot);
+const OUT_DIR = path.join(hostRoot, "public/prototypes/mobbin-references");
+
+function parseArgs(argv) {
+  const idsFlag = argv.find((arg) => arg.startsWith("--ids="));
+  if (idsFlag) {
+    const ids = idsFlag
+      .slice("--ids=".length)
+      .split(",")
+      .map((id) => id.trim())
+      .filter(Boolean);
+    if (ids.length === 0) {
+      throw new Error("--ids requires at least one screen id");
+    }
+    return ids;
+  }
+
+  const configFlag = argv.find((arg) => arg.startsWith("--config="));
+  if (configFlag) {
+    return { configPath: configFlag.slice("--config=".length) };
+  }
+
+  throw new Error(
+    "No screen ids provided. Pass --ids=id1,id2 or --config=path/to/ids.json",
+  );
+}
+
+async function loadScreenIds(argv) {
+  const parsed = parseArgs(argv);
+  if (Array.isArray(parsed)) return parsed;
+
+  const raw = await readFile(parsed.configPath, "utf8");
+  const config = JSON.parse(raw);
+  const ids = config.screenIds ?? config.ids;
+  if (!Array.isArray(ids) || ids.length === 0) {
+    throw new Error("Config must include a non-empty screenIds (or ids) array");
+  }
+  return ids;
+}
+
+function extractLargestSrcSetUrl(html) {
+  const srcSetMatch = html.match(/imageSrcSet="([^"]+)"/);
+  if (!srcSetMatch) return null;
+
+  const candidates = [];
+  const parts = srcSetMatch[1].split(/\s+/);
+  for (let i = 0; i < parts.length - 1; i += 2) {
+    const url = parts[i];
+    const width = parts[i + 1];
+    if (url?.startsWith("https://") && width?.endsWith("w")) {
+      candidates.push({ url, width: Number.parseInt(width, 10) });
+    }
+  }
+
+  candidates.sort((a, b) => b.width - a.width);
+  return candidates[0]?.url ?? null;
+}
+
+async function downloadScreen(screenId) {
+  const pageUrl = `https://mobbin.com/explore/screens/${screenId}`;
+  const response = await fetch(pageUrl, {
+    headers: { "User-Agent": "prototype-tool/1.0" },
+  });
+  if (!response.ok) {
+    throw new Error(`${screenId}: page fetch failed (${response.status})`);
+  }
+
+  const html = await response.text();
+  const imageUrl = extractLargestSrcSetUrl(html);
+  if (!imageUrl) {
+    throw new Error(`${screenId}: no srcset image found`);
+  }
+
+  const imageResponse = await fetch(imageUrl);
+  if (!imageResponse.ok) {
+    throw new Error(`${screenId}: image fetch failed (${imageResponse.status})`);
+  }
+
+  const buffer = Buffer.from(await imageResponse.arrayBuffer());
+  const outPath = path.join(OUT_DIR, `${screenId}.webp`);
+  await writeFile(outPath, buffer);
+  console.log(`Saved ${outPath} (${buffer.length} bytes)`);
+}
+
+const screenIds = await loadScreenIds(process.argv.slice(2));
+
+await mkdir(OUT_DIR, { recursive: true });
+
+for (const screenId of screenIds) {
+  await downloadScreen(screenId);
+}
+
+console.log("Done.");

package/scripts/lib/host-config.example.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+#
+# Host-owned sync/link config (TEMPLATE).
+#
+# Copy this to the host repo root as `prototype.sync.config.sh` and fill in
+# the values for YOUR app. The prototype package reads this file so that no
+# host-specific file names, component customizations, or source-app env var
+# names ever live inside the package itself.
+#
+# All paths are relative to the repo root and are mirrored 1:1 between the
+# source app and this host (e.g. source `src/lib/utils.ts` -> host
+# `src/lib/utils.ts`).
+
+# --- pnpm sync-from-source -------------------------------------------------
+
+# Single files to copy from the source app into this host.
+SYNC_FILES=(
+  "src/app/globals.css"
+  # "src/lib/utils.ts"
+)
+
+# Directories to copy recursively (contents merged into the host dir).
+SYNC_DIRS=(
+  # "src/components/ui"
+)
+
+# Globs to copy (each glob's parent dir is the destination).
+SYNC_GLOBS=(
+  # "public/fonts/*.woff2"
+)
+
+# Reminder list printed after a sync: files this host has customized beyond
+# the source version, which the blanket copy overwrites and you must re-apply.
+# Leave empty if the host does not diverge from source.
+SYNC_LOCAL_EXTENSIONS=(
+  # "my-component (local variant + semantic token classes)"
+)
+
+# --- pnpm link-source-db ---------------------------------------------------
+
+# Env var names to copy from the source app's .env.local into this host's.
+SOURCE_DB_ENV_VARS=(
+  # "MY_SERVICE_URL"
+  # "MY_SERVICE_KEY"
+)
+
+# Optional: console URL printed after a successful link.
+SOURCE_DB_CONSOLE_URL=""

package/scripts/lib/host-config.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+
+# Locate and source the host-owned sync/link config.
+#
+# The prototype package is host-agnostic: it must not name host files,
+# host component customizations, or source-app env vars. All of that lives
+# in a host-root config file owned by the consuming app.
+#
+# Resolution: PROTOTYPE_SYNC_CONFIG (env) > $HOST_ROOT/prototype.sync.config.sh
+#
+# See scripts/lib/host-config.example.sh for the expected shape.
+load_host_config() {
+  local host_root="$1"
+  local config="${PROTOTYPE_SYNC_CONFIG:-$host_root/prototype.sync.config.sh}"
+
+  if [[ ! -f "$config" ]]; then
+    echo "Host sync config not found at: $config" >&2
+    echo "Create it in the host repo root. Template:" >&2
+    echo "  packages/prototype/scripts/lib/host-config.example.sh" >&2
+    return 1
+  fi
+
+  # shellcheck disable=SC1090
+  source "$config"
+}

package/scripts/lib/resolve-host-root.mjs

@@ -0,0 +1,18 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export function resolveHostRoot(toolRootPath) {
+  let dir = path.resolve(toolRootPath, "..");
+  while (dir !== path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, "prototype.config.ts"))) {
+      return dir;
+    }
+    dir = path.dirname(dir);
+  }
+  return path.resolve(toolRootPath, "..", "..");
+}
+
+export function resolveToolRoot(importMetaUrl) {
+  return path.resolve(path.dirname(fileURLToPath(importMetaUrl)), "..");
+}

package/scripts/lib/source-path.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+
+# Walk up from the plugin root until we find prototype.config.ts (host repo root).
+resolve_host_root() {
+  local tool_root="$1"
+  local dir
+
+  dir="$(cd "$tool_root/.." && pwd)"
+  while [[ "$dir" != "/" ]]; do
+    if [[ -f "$dir/prototype.config.ts" ]]; then
+      printf '%s' "$dir"
+      return 0
+    fi
+    dir="$(dirname "$dir")"
+  done
+
+  # Fallback for the standard workspace layout: host/packages/prototype
+  (cd "$tool_root/../.." && pwd)
+}
+
+# Resolve source app path: SOURCE (shell) > SOURCE_PATH (env) > .env.local > source/ symlink
+resolve_source_path() {
+  local root="$1"
+  local raw="${SOURCE:-${SOURCE_PATH:-}}"
+
+  if [[ -z "$raw" && -f "$root/.env.local" ]]; then
+    raw="$(
+      grep -E '^SOURCE_PATH=' "$root/.env.local" | tail -1 | cut -d= -f2- \
+        | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//' \
+              -e 's/^"//' -e 's/"$//' -e "s/^'//" -e "s/'$//"
+    )"
+  fi
+
+  if [[ -z "$raw" && -L "$root/source" ]]; then
+    raw="$(readlink "$root/source")"
+  fi
+
+  if [[ -z "$raw" ]]; then
+    return 1
+  fi
+
+  raw="${raw/#\~/$HOME}"
+
+  if [[ "$raw" != /* ]]; then
+    raw="$root/$raw"
+  fi
+
+  (cd "$raw" 2>/dev/null && pwd) || return 1
+}

package/scripts/link-source-db.sh

@@ -0,0 +1,128 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+TOOL_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+# shellcheck source=lib/source-path.sh
+source "$TOOL_ROOT/scripts/lib/source-path.sh"
+# shellcheck source=lib/host-config.sh
+source "$TOOL_ROOT/scripts/lib/host-config.sh"
+HOST_ROOT="$(resolve_host_root "$TOOL_ROOT")"
+
+if ! load_host_config "$HOST_ROOT"; then
+  exit 1
+fi
+
+if [[ "${SOURCE_DB_ENV_VARS+set}" != set || "${#SOURCE_DB_ENV_VARS[@]}" -eq 0 ]]; then
+  echo "No SOURCE_DB_ENV_VARS configured in the host sync config." >&2
+  echo "Add the env var names to copy from the source app to prototype.sync.config.sh." >&2
+  exit 1
+fi
+
+TARGET="${1:-}"
+if [[ -z "$TARGET" ]]; then
+  if ! TARGET="$(resolve_source_path "$HOST_ROOT")"; then
+    echo "Set SOURCE_PATH in .env.local (see .env.example), or pass a path:" >&2
+    echo "  pnpm link-source-db /path/to/source-app" >&2
+    exit 1
+  fi
+elif [[ "$TARGET" != /* ]]; then
+  TARGET="$HOST_ROOT/$TARGET"
+fi
+
+SOURCE_ENV="$TARGET/.env.local"
+LOCAL_ENV="$HOST_ROOT/.env.local"
+
+if [[ ! -d "$TARGET" ]]; then
+  echo "Source app not found at: $TARGET" >&2
+  exit 1
+fi
+
+if [[ ! -f "$SOURCE_ENV" ]]; then
+  echo "Source env file not found at: $SOURCE_ENV" >&2
+  echo "Create it in the source app repo (see source app local dev docs)." >&2
+  exit 1
+fi
+
+extract_env() {
+  local file="$1"
+  local key="$2"
+  local line value
+
+  line="$(grep -E "^(#\s*)?${key}=" "$file" | tail -1 || true)"
+  if [[ -z "$line" ]]; then
+    return 1
+  fi
+
+  value="${line#"${line%%=*}"=}"
+  value="${value#"${value%%[![:space:]]*}"}"
+  value="${value%"${value##*[![:space:]]}"}"
+  value="${value#"${value%%[![:space:]]*}"}"
+  value="${value%"${value##*[![:space:]]}"}"
+
+  if [[ "$value" == \"*\" && "$value" == *\" ]]; then
+    value="${value:1:${#value}-2}"
+  elif [[ "$value" == \'*\' && "$value" == *\' ]]; then
+    value="${value:1:${#value}-2}"
+  fi
+
+  printf '%s' "$value"
+}
+
+upsert_env() {
+  local file="$1"
+  local key="$2"
+  local value="$3"
+  local tmp escaped
+
+  escaped="${value//\\/\\\\}"
+  escaped="${escaped//\"/\\\"}"
+
+  if [[ ! -f "$file" ]]; then
+    printf '%s="%s"\n' "$key" "$escaped" >>"$file"
+    return
+  fi
+
+  tmp="$(mktemp)"
+  if grep -q "^${key}=" "$file"; then
+    awk -v key="$key" -v value="$escaped" '
+      BEGIN { updated = 0 }
+      $0 ~ "^" key "=" {
+        print key "=\"" value "\""
+        updated = 1
+        next
+      }
+      { print }
+      END {
+        if (!updated) {
+          print key "=\"" value "\""
+        }
+      }
+    ' "$file" >"$tmp"
+  else
+    cp "$file" "$tmp"
+    printf '\n%s="%s"\n' "$key" "$escaped" >>"$tmp"
+  fi
+
+  mv "$tmp" "$file"
+}
+
+linked=0
+for key in "${SOURCE_DB_ENV_VARS[@]}"; do
+  if value="$(extract_env "$SOURCE_ENV" "$key")"; then
+    upsert_env "$LOCAL_ENV" "$key" "$value"
+    echo "Linked $key from $SOURCE_ENV"
+    linked=$((linked + 1))
+  fi
+done
+
+if [[ "$linked" -eq 0 ]]; then
+  echo "No configured vars found in $SOURCE_ENV." >&2
+  echo "Uncomment or add the SOURCE_DB_ENV_VARS entries in the source app's .env.local first." >&2
+  exit 1
+fi
+
+if [[ -n "${SOURCE_DB_CONSOLE_URL:-}" ]]; then
+  echo "Updated $LOCAL_ENV ($linked vars). Console: $SOURCE_DB_CONSOLE_URL"
+else
+  echo "Updated $LOCAL_ENV ($linked vars)."
+fi

package/scripts/link-source.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+TOOL_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+# shellcheck source=lib/source-path.sh
+source "$TOOL_ROOT/scripts/lib/source-path.sh"
+HOST_ROOT="$(resolve_host_root "$TOOL_ROOT")"
+
+LINK="$HOST_ROOT/source"
+TARGET="${1:-}"
+
+if [[ -z "$TARGET" ]]; then
+  if ! TARGET="$(resolve_source_path "$HOST_ROOT")"; then
+    echo "Set SOURCE_PATH in .env.local (see .env.example), or pass a path:" >&2
+    echo "  pnpm link-source /path/to/source-app" >&2
+    exit 1
+  fi
+elif [[ "$TARGET" != /* ]]; then
+  TARGET="$HOST_ROOT/$TARGET"
+fi
+
+if [[ ! -d "$TARGET" ]]; then
+  echo "Source app not found at: $TARGET" >&2
+  exit 1
+fi
+
+if [[ -L "$LINK" ]]; then
+  current="$(readlink "$LINK")"
+  if [[ "$current" == "$TARGET" ]] || [[ "$(cd "$HOST_ROOT" && cd "$current" 2>/dev/null && pwd)" == "$TARGET" ]]; then
+    echo "source/ already linked to: $TARGET"
+    exit 0
+  fi
+  rm "$LINK"
+elif [[ -e "$LINK" ]]; then
+  echo "source/ exists but is not a symlink — remove it first" >&2
+  exit 1
+fi
+
+ln -s "$TARGET" "$LINK"
+echo "Linked source/ -> $TARGET"

package/scripts/publish-package.sh

@@ -0,0 +1,147 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+TOOL_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$TOOL_ROOT"
+
+REGISTRY="https://registry.npmjs.org"
+DRY_RUN=0
+TAG="latest"
+SKIP_VERIFY=0
+OTP=""
+
+usage() {
+  cat <<EOF
+Usage: $(basename "$0") [options]
+
+Publish proto-plugin to npm.
+
+Options:
+  --dry-run        Validate the tarball without publishing
+  --tag <tag>      npm dist-tag (default: latest)
+  --otp <code>     One-time password from your authenticator app
+  --skip-verify    Skip pre-publish verification scripts
+  -h, --help       Show this help message
+
+Examples:
+  pnpm publish-package
+  pnpm publish-package --otp 123456
+  pnpm publish-package --dry-run
+  pnpm publish-package --tag next
+
+Requires: npm login (npm whoami must succeed).
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --dry-run)
+      DRY_RUN=1
+      shift
+      ;;
+    --tag)
+      TAG="${2:?Missing value for --tag}"
+      shift 2
+      ;;
+    --skip-verify)
+      SKIP_VERIFY=1
+      shift
+      ;;
+    --otp)
+      OTP="${2:?Missing value for --otp}"
+      shift 2
+      ;;
+    -h | --help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown option: $1" >&2
+      usage >&2
+      exit 1
+      ;;
+  esac
+done
+
+if [[ "$(node -pe "require('./package.json').private === true")" == "true" ]]; then
+  echo "package.json has \"private\": true, which blocks npm publish." >&2
+  echo "Remove it or set \"private\": false before publishing." >&2
+  exit 1
+fi
+
+if ! npm whoami --registry "$REGISTRY" >/dev/null 2>&1; then
+  echo "Not logged in to npm. Run: npm login" >&2
+  exit 1
+fi
+
+find_host_with_prototypes() {
+  local dir="$TOOL_ROOT/.."
+  while [[ "$dir" != "/" ]]; do
+    if [[ -f "$dir/prototype.config.ts" && -d "$dir/src/prototypes" ]]; then
+      echo "$dir"
+      return 0
+    fi
+    dir="$(dirname "$dir")"
+  done
+  return 1
+}
+
+if [[ "$SKIP_VERIFY" -eq 0 ]]; then
+  if host_root="$(find_host_with_prototypes)"; then
+    echo "Running verification scripts against $host_root..."
+    npm run verify:prototype-ids
+    npm run verify:prototype-preview-states
+  else
+    echo "Skipping verification (no host app with prototypes found)."
+  fi
+fi
+
+PACKAGE_NAME="$(node -pe "require('./package.json').name")"
+PACKAGE_VERSION="$(node -pe "require('./package.json').version")"
+
+echo "Publishing ${PACKAGE_NAME}@${PACKAGE_VERSION}"
+echo "Registry: ${REGISTRY}"
+echo "Access: public (unscoped)"
+
+PUBLISH_ARGS=(--registry "$REGISTRY" --tag "$TAG")
+
+if [[ -n "$OTP" ]]; then
+  PUBLISH_ARGS+=(--otp "$OTP")
+fi
+
+if [[ "$DRY_RUN" -eq 1 ]]; then
+  PUBLISH_ARGS+=(--dry-run)
+  echo "Dry run — tarball will not be uploaded."
+fi
+
+env -u NPM_CONFIG_REGISTRY -u NPM_CONFIG_CAFILE \
+  npm publish "${PUBLISH_ARGS[@]}" || {
+  status=$?
+  if [[ "$DRY_RUN" -eq 0 && "$status" -ne 0 ]]; then
+    echo >&2
+    echo "Publish failed." >&2
+    if [[ "$PACKAGE_NAME" == @*/* ]]; then
+      scope="${PACKAGE_NAME%%/*}"
+      scope="${scope#@}"
+      whoami="$(npm whoami --registry "$REGISTRY" 2>/dev/null || true)"
+      echo "Logged in as: ${whoami:-unknown}" >&2
+      echo "Package scope: @${scope}" >&2
+      if [[ -n "$whoami" && "$whoami" != "$scope" ]]; then
+        echo >&2
+        echo "npm often returns 404 when your account cannot publish to this scope." >&2
+        echo "Fix one of:" >&2
+        echo "  1. npm logout && npm login   # sign in as the @${scope} npm user/org owner" >&2
+        echo "  2. Add @${whoami} to the @${scope} org at https://www.npmjs.com/settings/${scope}/members" >&2
+        echo "  3. Rename the package to @${whoami}/prototype in package.json" >&2
+      fi
+    fi
+  fi
+  exit "$status"
+}
+
+if [[ "$DRY_RUN" -eq 0 ]]; then
+  echo "Published successfully."
+  echo "Install with:"
+  echo "  npm install ${PACKAGE_NAME}@${PACKAGE_VERSION}"
+  echo "  pnpm add ${PACKAGE_NAME}@${PACKAGE_VERSION}"
+fi