docs(docs): add starlight site and alpha safeguards

Author: crup

.github/workflows/docs.yml

@@ -51,7 +51,7 @@ jobs:
       - name: Upload Pages artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: docs-api
+          path: docs-dist
 
       - name: Deploy Pages
         id: deployment

.github/workflows/prerelease.yml

@@ -3,15 +3,6 @@ name: Prerelease
 on:
   workflow_dispatch:
     inputs:
-      tag:
-        description: npm dist-tag to publish
-        required: true
-        default: alpha
-        type: choice
-        options:
-          - alpha
-          - beta
-          - rc
       version_base:
         description: Base version before prerelease suffix
         required: true
@@ -51,7 +42,7 @@ jobs:
 
       - name: Set prerelease version
         env:
-          PACKAGE_VERSION: ${{ inputs.version_base }}-${{ inputs.tag }}.${{ github.run_number }}
+          PACKAGE_VERSION: ${{ inputs.version_base }}-alpha.${{ github.run_number }}
         run: |
           node -e "const fs = require('node:fs'); const pkg = JSON.parse(fs.readFileSync('package.json', 'utf8')); pkg.version = process.env.PACKAGE_VERSION; fs.writeFileSync('package.json', JSON.stringify(pkg, null, 2) + '\n');"
           node -e "const pkg = require('./package.json'); console.log(pkg.name + '@' + pkg.version);"
@@ -62,7 +53,16 @@ jobs:
           pnpm size
 
       - name: Publish prerelease
-        run: pnpm publish --tag "${{ inputs.tag }}" --access public --no-git-checks
+        run: pnpm publish --tag alpha --access public --no-git-checks
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Keep npm latest on current alpha
+        run: |
+          PACKAGE_NAME=$(node -p "require('./package.json').name")
+          PACKAGE_VERSION=$(node -p "require('./package.json').version")
+          npm dist-tag add "$PACKAGE_NAME@$PACKAGE_VERSION" latest
         env:
           NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.github/workflows/release.yml

@@ -2,6 +2,11 @@ name: Release
 
 on:
   workflow_dispatch:
+    inputs:
+      confirm_stable_release:
+        description: Type "publish-stable" to publish the latest dist-tag.
+        required: true
+        default: alpha-only
 
 permissions:
   contents: write
@@ -14,6 +19,7 @@ concurrency:
 
 jobs:
   release:
+    if: github.ref_name == 'main' && inputs.confirm_stable_release == 'publish-stable'
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -47,3 +53,13 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+  stable-release-locked:
+    if: inputs.confirm_stable_release != 'publish-stable'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Stable release is locked
+        run: |
+          echo "Stable npm publishing is disabled by default."
+          echo "Use the Prerelease workflow for alpha releases."
+          echo "To intentionally publish latest, rerun this workflow with confirm_stable_release=publish-stable on main."

.github/workflows/size.yml

@@ -8,6 +8,7 @@ on:
 
 permissions:
   contents: read
+  pull-requests: write
 
 jobs:
   compare:
@@ -50,10 +51,36 @@ jobs:
           node scripts/size-report.mjs --json > ../base-size.json
 
       - name: Compare size
+        id: compare
         run: |
           if [ -f base-size.json ]; then
-            node head/scripts/size-compare.mjs base-size.json head-size.json >> "$GITHUB_STEP_SUMMARY"
+            node head/scripts/size-compare.mjs base-size.json head-size.json | tee size-summary.md >> "$GITHUB_STEP_SUMMARY"
           else
             echo "Base branch does not have size tooling yet. Head size:" >> "$GITHUB_STEP_SUMMARY"
             cat head-size.json >> "$GITHUB_STEP_SUMMARY"
+            {
+              echo "Base branch does not have size tooling yet. Head size:"
+              cat head-size.json
+            } > size-summary.md
           fi
+
+      - name: Comment size report
+        if: github.event_name == 'pull_request'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('node:fs');
+            const marker = '<!-- react-timer-hook-size-report -->';
+            const body = `${marker}
+            ## Bundle size
+
+            ${fs.readFileSync('size-summary.md', 'utf8')}`;
+            const { owner, repo } = context.repo;
+            const issue_number = context.issue.number;
+            const comments = await github.rest.issues.listComments({ owner, repo, issue_number, per_page: 100 });
+            const existing = comments.data.find(comment => comment.body?.includes(marker));
+            if (existing) {
+              await github.rest.issues.updateComment({ owner, repo, comment_id: existing.id, body });
+            } else {
+              await github.rest.issues.createComment({ owner, repo, issue_number, body });
+            }

.gitignore

@@ -129,6 +129,8 @@ out
 .nuxt
 dist
 docs-api
+docs-dist
+.astro
 
 # Gatsby files
 .cache/

.npmignore

@@ -0,0 +1,5 @@
+*
+!dist/**
+!README.md
+!LICENSE
+!package.json

CONTRIBUTING.md

@@ -2,13 +2,11 @@
 
 Thanks for considering a contribution.
 
-This project aims to stay small, deterministic, and heavily tested. Please read the requirements and API docs before proposing API changes:
+This project aims to stay small, deterministic, and heavily tested. Please read the public docs before proposing API changes:
 
-- [Requirements](./REQUIREMENTS.md)
-- [API Specification](./docs/API.md)
-- [Implementation Plan](./docs/IMPLEMENTATION.md)
-- [Task Plan](./docs/TASKS.md)
-- [Branching and Commits](./docs/BRANCHING_AND_COMMITS.md)
+- [Docs](https://crup.github.io/react-timer-hook/)
+- [useTimer](https://crup.github.io/react-timer-hook/api/use-timer/)
+- [useTimerGroup](https://crup.github.io/react-timer-hook/api/use-timer-group/)
 
 ## Project Boundaries
 
@@ -50,12 +48,20 @@ pnpm test
 pnpm typecheck
 pnpm build
 pnpm docs:build
+pnpm size
 pnpm readme:check
 ```
 
 ## Branches and Commit Messages
 
-Use `feature/timer-core-v1` for the first implementation branch.
+Use short-lived branches:
+
+- `feature/*` for features
+- `fix/*` for fixes
+- `docs/*` for docs
+- `chore/*` for maintenance
+
+Alpha releases are published from `next`. Stable publishing is manually locked until the project intentionally switches to final releases.
 
 Use Conventional Commits:
 
@@ -73,8 +79,6 @@ docs(release): document alpha prerelease flow
 
 Commit messages are enforced with commitlint through Husky. Changesets still own package versioning.
 
-See [Branching and Commits](./docs/BRANCHING_AND_COMMITS.md) for the full branch, alpha, beta, release-candidate, and stable release flow.
-
 ## API Change Rules
 
 Prefer recipes over new API.