@hirobius/design-system 0.8.1

package/package.json

@@ -0,0 +1,366 @@
+{
+  "name": "@hirobius/design-system",
+  "description": "Hirobius Design Systems Architecture: token-governed React components, documentation surfaces, and distribution tooling.",
+  "private": false,
+  "version": "0.8.1",
+  "engines": {
+    "node": ">=20",
+    "pnpm": ">=8"
+  },
+  "type": "module",
+  "typeCoverage": {
+    "ignoreFiles": [
+      "src/app/components/mobius-distortion.ts"
+    ]
+  },
+  "module": "./dist/hirobius-ui.js",
+  "types": "./dist/types/src/index.d.ts",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/types/src/index.d.ts",
+      "import": "./dist/hirobius-ui.js",
+      "default": "./dist/hirobius-ui.js"
+    },
+    "./tokens.css": "./dist/tokens.css",
+    "./variables.css": "./dist/variables.css",
+    "./tokens": {
+      "types": "./dist/types/src/app/design-system/tokens.d.ts",
+      "import": "./dist/tokens.js",
+      "default": "./dist/tokens.js"
+    },
+    "./cn": {
+      "types": "./dist/types/src/lib/utils.d.ts",
+      "import": "./dist/cn.js",
+      "default": "./dist/cn.js"
+    },
+    "./manifest": {
+      "types": "./dist/types/src/lib/manifest-entry.d.ts",
+      "import": "./dist/manifest.js",
+      "default": "./dist/manifest.js"
+    },
+    "./contexts": {
+      "types": "./dist/types/src/app/context/index.d.ts",
+      "import": "./dist/contexts.js",
+      "default": "./dist/contexts.js"
+    },
+    "./form": {
+      "types": "./dist/types/src/form/index.d.ts",
+      "import": "./dist/form.js",
+      "default": "./dist/form.js"
+    },
+    "./protocol": {
+      "import": "./protocol/envelope.mjs",
+      "default": "./protocol/envelope.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "protocol/envelope.mjs",
+    "protocol/figma-snapshot.schema.json",
+    "hirobius.tokens.json",
+    "public/hds-manifest.json"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@hookform/resolvers": "^3.9.0 || ^4.0.0 || ^5.0.0",
+    "react": "^18.3.0 || ^19.0.0",
+    "react-dom": "^18.3.0 || ^19.0.0",
+    "react-hook-form": "^7.0.0",
+    "react-router": "^7.0.0",
+    "zod": "^3.23.0 || ^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react-router": {
+      "optional": true
+    },
+    "react-hook-form": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    },
+    "@hookform/resolvers": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@radix-ui/react-dialog": "^1.1.15",
+    "@radix-ui/react-dropdown-menu": "^2.1.18",
+    "@radix-ui/react-popover": "^1.1.17",
+    "@radix-ui/react-select": "^2.3.1",
+    "@radix-ui/react-slot": "^1.2.4",
+    "@radix-ui/react-tabs": "^1.1.13",
+    "@radix-ui/react-toast": "^1.2.17",
+    "@radix-ui/react-toggle-group": "^1.1.13",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "lucide-react": "0.487.0",
+    "motion": "12.23.24",
+    "tailwind-merge": "^3.5.0"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.4",
+    "@axe-core/playwright": "^4.11.1",
+    "@changesets/cli": "^2.27.10",
+    "@cyclonedx/cyclonedx-npm": "^4.2.1",
+    "@hookform/resolvers": "^5.4.0",
+    "@lhci/cli": "0.15.1",
+    "@microsoft/api-extractor": "7.58.7",
+    "@playwright/test": "^1.58.2",
+    "@size-limit/file": "^12.1.0",
+    "@storybook/addon-a11y": "^8.6.18",
+    "@storybook/addon-essentials": "^8.6.14",
+    "@storybook/react": "^8.6.18",
+    "@storybook/react-vite": "^8.6.18",
+    "@tailwindcss/vite": "^4.2.4",
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/react": "^16.1.0",
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
+    "@types/three": "^0.183.1",
+    "@typescript-eslint/eslint-plugin": "^8.59.1",
+    "@typescript-eslint/parser": "^8.59.1",
+    "@vitejs/plugin-react": "4.7.0",
+    "@vitest/coverage-v8": "^4.1.0",
+    "acorn": "^8.16.0",
+    "acorn-jsx": "^5.3.2",
+    "chromatic": "^17.6.0",
+    "cors": "^2.8.6",
+    "editorconfig-checker": "^6.1.1",
+    "eslint": "^10.3.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-import-resolver-typescript": "^4.4.4",
+    "eslint-plugin-import-x": "^4.16.2",
+    "eslint-plugin-jsx-a11y": "^6.10.2",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "eslint-plugin-tailwindcss": "^3.18.3",
+    "express": "^5.2.1",
+    "fast-check": "^4.7.0",
+    "fuse.js": "^7.1.0",
+    "globals": "^17.6.0",
+    "husky": "^9.1.7",
+    "jscodeshift": "^17.3.0",
+    "jsdom": "^29.0.0",
+    "knip": "^6.10.0",
+    "lint-staged": "^17.0.2",
+    "nodemon": "^3.1.14",
+    "pixelmatch": "^7.1.0",
+    "playwright": "^1.58.2",
+    "pngjs": "^7.0.0",
+    "prettier": "^3.8.3",
+    "publint": "^0.3.21",
+    "react": "18.3.1",
+    "react-docgen-typescript": "^2.4.0",
+    "react-dom": "18.3.1",
+    "react-hook-form": "^7.80.0",
+    "react-router": "7.13.0",
+    "size-limit": "^12.1.0",
+    "storybook": "^8.6.18",
+    "style-dictionary": "^5.4.0",
+    "tailwindcss": "^4.2.4",
+    "three": "^0.183.2",
+    "type-coverage": "^2.29.7",
+    "typescript": "^6.0.2",
+    "vite": "6.4.2",
+    "vite-bundle-visualizer": "^1.2.1",
+    "vitest": "^4.1.0",
+    "zod": "^4.4.3",
+    "zustand": "^5.0.12"
+  },
+  "size-limit": [
+    {
+      "name": "library esm (main barrel)",
+      "path": "dist/hirobius-ui.js",
+      "limit": "220 kB"
+    },
+    {
+      "name": "library css (tokens + base)",
+      "path": "dist/tokens.css",
+      "limit": "24 kB"
+    },
+    {
+      "name": "subpath: cn helper",
+      "path": "dist/cn.js",
+      "limit": "1 kB"
+    },
+    {
+      "name": "subpath: token bridge",
+      "path": "dist/tokens.js",
+      "limit": "8 kB"
+    },
+    {
+      "name": "subpath: manifest (json-as-esm)",
+      "path": "dist/manifest.js",
+      "limit": "60 kB"
+    }
+  ],
+  "lint-staged": {
+    "*.{ts,tsx,js,jsx,mjs,cjs,json,md,mdx,css,scss,html,yaml,yml}": "prettier --write"
+  },
+  "scripts": {
+    "_comment:a11y-high-value": "The following check:* validators are high-value accessibility checks that catch real violations (check:focus found 1 missing focus class). Kept dormant/manual-only to avoid pre-commit performance regression. Candidates to wire into pretest after CI stability review.",
+    "_comment:link-integrity": "check:doc-refs and check:routes both validate internal link integrity (different surfaces: doc refs vs route links). Kept dormant/manual-only to prevent pre-commit cascade.",
+    "_comment:security-baseline": "check:security validates OWASP baseline patterns. Dormant/manual-only — candidate for integration into security-focused CI lane, not pretest.",
+    "_comment:token-integrity": "check:css-values, check:token-structure validate token system correctness. Dormant/manual-only due to overlapping scope with check:fast and existing token validators.",
+    "_comment:editorconfig-version": "check:mojibake pins EC_VERSION=v3.7.0. The editorconfig-checker@6.1.x npm wrapper expects binary v3.7.0 but downloads the latest Go release (v3.8.0, 2026-06-25), so a fresh install fails with a version mismatch (binary != config). Pinning the download to the wrapper's expected version keeps CI + pre-commit green. Bump both together when upgrading the npm package. All editorconfig-checker calls route through check:mojibake.",
+    "api:check": "node scripts/audit-component-integrity.mjs --api",
+    "api:update": "node scripts/audit-component-integrity.mjs --api --update-baseline",
+    "assets:convert": "node scripts/convert-incoming-assets.mjs",
+    "assets:manifest": "node scripts/sync-asset-manifest.mjs",
+    "audit:bundle": "node scripts/audit-bundle.mjs",
+    "audit:deps": "node scripts/audit-deps.mjs",
+    "audit:sbom": "node scripts/audit-sbom.mjs",
+    "audit:sidecar": "node scripts/generate-security-posture.mjs",
+    "audit:style-dictionary": "bash scripts/poc/style-dictionary-poc/run.sh",
+    "bridge": "node --env-file=.env.local scripts/hds-bridge.mjs",
+    "build": "pnpm sync:health && node scripts/sync-icons.mjs && vite build --configLoader native",
+    "build:ssr": "vite build --ssr src/entry-server.tsx --outDir .ssr-cache --configLoader native",
+    "build:prerender": "pnpm build && pnpm build:ssr && node scripts/prerender.mjs",
+    "build:lib": "vite build -c vite.config.lib.ts && pnpm build:types && node scripts/build-vars-css.mjs && node scripts/embed-fonts.mjs",
+    "build:types": "tsc -p tsconfig.dts.json && node scripts/strip-dts-side-effects.mjs",
+    "catalog": "node scripts/generate-visual-catalog.mjs",
+    "changelog:generate": "node scripts/generate-changelog.mjs",
+    "changeset": "changeset",
+    "changeset:add": "changeset",
+    "changeset:version": "changeset version",
+    "codemod": "jscodeshift --parser=tsx --extensions=tsx,ts",
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build",
+    "chromatic": "chromatic --exit-zero-on-changes",
+    "release": "pnpm build:lib && pnpm smoke:consumer --skip-build && changeset publish",
+    "check": "pnpm check:full",
+    "check:a11y": "pnpm lint --rule '{\"jsx-a11y/alt-text\":\"error\",\"jsx-a11y/img-redundant-alt\":\"error\"}'",
+    "check:assets": "node scripts/check-asset-manifest.mjs",
+    "check:attributions": "node scripts/check-attributions.mjs",
+    "check:binding-drift": "node scripts/check-binding-drift.mjs",
+    "check:brand": "node scripts/check-brand.mjs",
+    "check:breakpoints": "node scripts/check-hardcoded-breakpoints.mjs",
+    "check:colors": "node scripts/check-hardcoded-colors.mjs",
+    "check:contrast": "node scripts/check-contrast.mjs",
+    "check:css": "node scripts/check-css-integrity.mjs",
+    "check:css-values": "node scripts/check-style-discipline.mjs --css-values-only",
+    "check:dimensions": "node scripts/check-dimensions.mjs",
+    "check:doc-refs": "node scripts/check-link-integrity.mjs --doc-refs-only",
+    "check:doc-structure": "node scripts/check-doc-structure.mjs",
+    "check:docs": "node scripts/audit-component-integrity.mjs --docs && node scripts/check-frozen-demos.mjs && node scripts/check-token-descriptions.mjs --no-missing --quality",
+    "check:exemptions": "node scripts/check-exemptions.mjs",
+    "check:fast": "node scripts/validate-manifest.mjs && node scripts/check-manifest-drift.mjs && node scripts/sync-asset-manifest.mjs && node scripts/build-tokens.mjs && node scripts/build-roadmap-data.mjs && node scripts/verify-tokens.mjs && node scripts/audit-tokens.mjs --full && pnpm typecheck && node scripts/check-css-integrity.mjs && node scripts/audit-component-integrity.mjs --tokens && pnpm check:docs && node scripts/check-ref-forwarding.mjs && node scripts/check-hardcoded-spacing.mjs && node scripts/check-dimensions.mjs && node scripts/check-hardcoded-breakpoints.mjs && node scripts/check-typography-discipline.mjs && pnpm check:mojibake && node scripts/check-mono-roles.mjs && node scripts/check-style-discipline.mjs --style-props-only && node scripts/check-tier-bypass.mjs && node scripts/check-link-integrity.mjs --doc-refs-only && node scripts/check-link-integrity.mjs --route-links-only && node scripts/check-brand.mjs && node scripts/check-registry.mjs && node scripts/check-asset-manifest.mjs && node scripts/check-template-source-of-truth.mjs",
+    "check:figma-snapshot": "node scripts/test-figma-masters-snapshot.mjs",
+    "check:figma-snapshot:update": "node scripts/test-figma-masters-snapshot.mjs --update",
+    "check:focus": "node scripts/check-focus-states.mjs",
+    "check:font-files": "node scripts/check-typography-discipline.mjs --font-files-only",
+    "check:fonts": "node scripts/check-typography-discipline.mjs --fonts-only",
+    "check:forbidden-overrides": "node scripts/audit-tokens.mjs --forbidden",
+    "check:format": "pnpm exec lint-staged",
+    "check:full": "node scripts/validate-manifest.mjs && node scripts/check-manifest-drift.mjs && node scripts/sync-asset-manifest.mjs && node scripts/build-tokens.mjs && node scripts/verify-tokens.mjs && node scripts/audit-tokens.mjs --full && pnpm typecheck && node scripts/check-css-integrity.mjs && node scripts/audit-component-integrity.mjs --tokens && node scripts/audit-pages.mjs && pnpm check:docs && node scripts/check-doc-structure.mjs && node scripts/check-contrast.mjs && node scripts/check-focus-states.mjs && node scripts/check-reduced-motion.mjs && node scripts/check-ref-forwarding.mjs && node scripts/check-hardcoded-spacing.mjs && node scripts/check-dimensions.mjs && node scripts/check-hardcoded-breakpoints.mjs && node scripts/check-unresponsive-grids.mjs && node scripts/check-page-shell.mjs && node scripts/check-motion.mjs && node scripts/check-typography-discipline.mjs && pnpm check:mojibake && node scripts/check-mono-roles.mjs && node scripts/check-style-discipline.mjs && node scripts/check-hardcoded-colors.mjs && node scripts/check-tier-bypass.mjs && node scripts/check-token-structure.mjs && node scripts/check-link-integrity.mjs && node scripts/check-og-meta.mjs && node scripts/check-asset-manifest.mjs && node scripts/check-security-baseline.mjs && node scripts/check-attributions.mjs && node scripts/check-exemptions.mjs && node scripts/check-brand.mjs && node scripts/check-registry.mjs && node scripts/audit-component-integrity.mjs --api && node scripts/check-token-descriptions.mjs --no-missing && node scripts/check-token-renames.mjs",
+    "check:ghost-tokens": "node scripts/audit-tokens.mjs --full",
+    "check:grids": "node scripts/check-unresponsive-grids.mjs",
+    "check:inline-styles": "node scripts/check-style-discipline.mjs --inline-only",
+    "check:knip": "knip",
+    "check:knip-ratchet": "knip --max-issues 60",
+    "check:licenses": "node scripts/check-licenses.mjs",
+    "check:lockfile": "pnpm install --frozen-lockfile --offline --prefer-offline --ignore-scripts --silent 2>/dev/null || (echo 'Lockfile drift: run pnpm install' && exit 1)",
+    "check:manifest-drift": "node scripts/check-manifest-drift.mjs",
+    "check:micromotion": "node scripts/check-motion.mjs",
+    "check:mojibake": "EC_VERSION=v3.7.0 pnpm exec editorconfig-checker",
+    "check:mono-roles": "node scripts/check-mono-roles.mjs",
+    "check:motion": "node scripts/check-reduced-motion.mjs",
+    "check:page-shell": "node scripts/check-page-shell.mjs",
+    "check:refs": "node scripts/check-ref-forwarding.mjs",
+    "check:registry": "node scripts/check-registry.mjs",
+    "check:release": "pnpm check:full && node scripts/check-style-discipline.mjs && pnpm build && pnpm perf:budget && pnpm test:a11y && pnpm test:visual && pnpm test:responsive && pnpm test:collision && pnpm check:size",
+    "check:routes": "node scripts/check-link-integrity.mjs --route-links-only",
+    "check:secrets": "node scripts/check-secrets.mjs",
+    "check:security": "node scripts/check-security-baseline.mjs",
+    "check:semantic-report": "node scripts/audit-tokens.mjs --report-only",
+    "check:size": "pnpm build:lib && size-limit",
+    "check:spacing": "node scripts/check-hardcoded-spacing.mjs",
+    "check:style-props": "node scripts/check-style-discipline.mjs --style-props-only",
+    "check:tailwind": "pnpm lint --rule '{\"tailwindcss/no-custom-classname\":\"error\"}'",
+    "check:tailwind-arbitrary": "pnpm lint --rule '{\"tailwindcss/no-arbitrary-value\":\"error\"}'",
+    "check:template-sot": "node scripts/check-template-source-of-truth.mjs",
+    "check:tier-bypass": "node scripts/check-tier-bypass.mjs",
+    "check:token-descriptions": "node scripts/check-token-descriptions.mjs --no-missing",
+    "check:token-renames": "node scripts/check-token-renames.mjs",
+    "check:token-structure": "node scripts/check-token-structure.mjs",
+    "check:tokens": "node scripts/check-hardcoded-colors.mjs && pnpm lint --rule '{\"tailwindcss/no-custom-classname\":\"error\"}' && node scripts/audit-tokens.mjs --forbidden && node scripts/check-tier-bypass.mjs && node scripts/check-hardcoded-spacing.mjs && node scripts/check-typography-discipline.mjs --fonts-only",
+    "check:type-coverage": "pnpm exec type-coverage --at-least 99.9",
+    "closure:plan": "node scripts/run-gates.mjs --channel pre-commit --emit-inventory docs/guardrails/full-strictness-inventory.json && node scripts/generate-closure-plan.mjs",
+    "closure:plan:check": "node scripts/generate-closure-plan.mjs --check",
+    "dev": "node scripts/generate-manifest.mjs && node scripts/sync-asset-manifest.mjs && node scripts/generate-component-api.mjs && node scripts/sync-icons.mjs && node scripts/build-tokens.mjs && node scripts/build-roadmap-data.mjs && vite --configLoader native",
+    "docs:api": "node scripts/generate-component-api.mjs",
+    "docs:changelogs": "node scripts/generate-component-changelogs.mjs",
+    "docs:llms": "node scripts/generate-llms-txt.mjs",
+    "figma-variables": "node scripts/build-figma-variables.mjs",
+    "figma:bridge:smoke": "node scripts/figma-bridge-smoke.mjs",
+    "figma:diff": "node scripts/figma-diff.mjs",
+    "figma:snapshot": "node scripts/normalize-figma-snapshot.mjs",
+    "figma:stream": "node scripts/llm-stream-bridge.mjs",
+    "guardrail:firing-stats": "node scripts/refresh-firing-stats.mjs",
+    "heal": "node scripts/self-heal.mjs",
+    "heal:smoke": "node scripts/self-heal.mjs --smoke",
+    "health-commit": "pnpm check:semantic-report && node scripts/print-health-commit.mjs",
+    "icons:sync": "node scripts/sync-icons.mjs",
+    "knip": "knip",
+    "lint": "eslint src scripts validators tests",
+    "lint:fix": "eslint src scripts validators tests --fix",
+    "llms:generate": "node scripts/generate-llms-txt.mjs",
+    "manifest:generate": "node scripts/generate-manifest.mjs && node scripts/generate-component-api.mjs && node scripts/enrich-manifest.mjs",
+    "manifest:project": "node scripts/generate-manifest-projection.mjs",
+    "nav:generate": "node scripts/generate-nav-model.mjs",
+    "perf:budget": "node -e \"require('fs').readdirSync('.lighthouseci').filter(f=>f.startsWith('lhr-')).forEach(f=>require('fs').unlinkSync('.lighthouseci/'+f))\" 2>/dev/null; lhci collect --config=.lighthouserc.json && lhci assert --config=.lighthouserc.json; find . -maxdepth 1 -type d -name 'C:*' -exec rm -rf {} + 2>/dev/null; true",
+    "prebuild": "node scripts/validate-manifest.mjs",
+    "prebuild:lib": "node scripts/generate-component-api.mjs",
+    "pretest": "node scripts/validate-manifest.mjs && node scripts/check-manifest-drift.mjs && node scripts/check-manifest-schema-semver.mjs && node scripts/audit-component-integrity.mjs --completeness && node scripts/check-source-canon.mjs && node scripts/check-binding-drift.mjs && node scripts/test-figma-masters-snapshot.mjs && node scripts/test-doc-pages-snapshot.mjs && node scripts/check-registry.mjs && node scripts/check-tenant-tokens.mjs && knip --no-exit-code",
+    "promote": "node scripts/promote.mjs",
+    "roadmap:data": "node scripts/build-roadmap-data.mjs && node scripts/verify-roadmap-sync.mjs",
+    "roadmap:verify": "node scripts/verify-roadmap-sync.mjs",
+    "roadmap:watch": "node scripts/watch-roadmap.mjs",
+    "scaffold:component": "node scripts/scaffold-component.mjs",
+    "scaffold:tenant": "node scripts/scaffold-tenant.mjs",
+    "sitemap:generate": "node scripts/generate-sitemap.mjs",
+    "size-limit": "size-limit --config .size-limit.cjs",
+    "smoke:consumer": "node scripts/smoke-consumer.mjs",
+    "sync": "node scripts/build-tokens.mjs && node scripts/audit-tokens.mjs --forbidden && node scripts/build-handoff.mjs && node scripts/build-design-md.mjs && node scripts/build-figma-variables.mjs",
+    "sync:health": "node scripts/generate-manifest.mjs && node scripts/generate-component-api.mjs && node scripts/enrich-manifest.mjs && node scripts/sync-asset-manifest.mjs && node scripts/build-tokens.mjs && node scripts/audit-tokens.mjs --report-only && node scripts/build-design-md.mjs && node scripts/build-roadmap-data.mjs && node scripts/verify-roadmap-sync.mjs",
+    "test": "vitest run --passWithNoTests",
+    "test:a11y": "playwright test tests/a11y.spec.ts",
+    "test:collision": "playwright test tests/collision.spec.ts",
+    "test:compiler": "node -e \"import('./scripts/hds-jsx-compiler.mjs').then(m => console.log(JSON.stringify(m.compile(process.argv[1]), null, 2)))\" --",
+    "test:coverage": "vitest run --coverage",
+    "test:figma": "npx tsx scripts/figma-sync.ts",
+    "test:layout": "node scripts/check-route-coverage.mjs && playwright test tests/layout-integrity.spec.ts",
+    "test:phase1": "node scripts/test-phase1.mjs",
+    "test:prompts": "node scripts/test-prompt-regression.mjs",
+    "test:responsive": "playwright test tests/responsive.spec.ts",
+    "test:visual": "playwright test tests/visual.spec.ts",
+    "test:visual:update": "playwright test tests/visual.spec.ts --update-snapshots",
+    "test:watch": "vitest",
+    "tokens": "node scripts/generate-manifest.mjs && node scripts/build-tokens.mjs && node scripts/audit-tokens.mjs --forbidden && node scripts/check-typography-discipline.mjs --overrides-only && node scripts/sync-hds-registry.mjs && node scripts/build-handoff.mjs && node scripts/build-design-md.mjs && node scripts/generate-llms-txt.mjs",
+    "tokens:audit": "node scripts/audit-component-integrity.mjs --tokens",
+    "tokens:audit:pages": "node scripts/audit-pages.mjs",
+    "tokens:build": "node scripts/build-hds-tokens.mjs",
+    "tokens:index": "node scripts/build-token-index.mjs",
+    "tokens:verify": "node scripts/build-tokens.mjs && node scripts/verify-tokens.mjs",
+    "typecheck": "tsc --noEmit -p tsconfig.typecheck.json",
+    "ui:fix": "node scripts/generate-to-figma.mjs --fix",
+    "ui:gen": "node scripts/generate-to-figma.mjs",
+    "ui:lint": "node scripts/ui-lint.mjs",
+    "ui:masters": "node scripts/build-figma-masters.mjs",
+    "validate:manifest": "node scripts/validate-manifest.mjs",
+    "visual-ingest": "node scripts/visual-ingest.mjs",
+    "watch:guardrails": "nodemon --watch CLAUDE.md --watch .cursorrules --watch eslint.config.js --watch .github/workflows -e md,json,js,yml,yaml --exec \"node scripts/audit-guardrails.js\"",
+    "watch:metrics": "nodemon --watch src/app/components --watch src/app/pages --watch src/app/design-system --watch src/app/styles -e tsx,ts,css --exec \"node scripts/audit-tokens.mjs --full && node scripts/generate-manifest.mjs\"",
+    "loop:validate": "node scripts/loop/loop-cli.mjs validate",
+    "loop:next": "node scripts/loop/loop-cli.mjs next",
+    "loop:status": "node scripts/loop/loop-cli.mjs status"
+  }
+}

package/protocol/envelope.mjs

@@ -0,0 +1,201 @@
+/**
+ * protocol/envelope.mjs
+ *
+ * Message-envelope protocol for bridge↔plugin traffic. Build unit p5-1.
+ *
+ * Envelope shape:
+ *   {
+ *     id:        string  (UUID v4)
+ *     type:      string  (verb, e.g. "selection.update")
+ *     payload:   object
+ *     timestamp: number  (ms since epoch)
+ *     hmac:      string  (HMAC-SHA256(secret, stableStringify({id,type,timestamp,payload})))
+ *   }
+ *
+ * The Figma plugin sandbox cannot import from this file. The mirror
+ * implementation lives at `figma-agent-plugin/protocol-envelope.js` and
+ * MUST stay byte-equivalent in HMAC output for the same inputs.
+ *
+ * Schema decisions (also documented in the unit's commit body):
+ *   - Clock-skew tolerance: ±60s on either side of now.
+ *   - Hard expiry:           5 minutes (300_000 ms) past `timestamp`.
+ *   - Replay-protection set: in-memory Map, FIFO-evicted at 1000 entries.
+ *
+ * Hard rules (CLAUDE.md / OPERATOR_BRIEF.md):
+ *   - No new npm dependencies; native Node crypto only.
+ *   - This file is the protocol library only — wiring the envelope into
+ *     hds-bridge.mjs / plugin code.js belongs to p5-2 and p5-3.
+ */
+
+import crypto from 'node:crypto';
+
+export const CLOCK_SKEW_MS = 60_000;     // ±60s tolerance for future timestamps
+export const MAX_AGE_MS = 5 * 60_000;    // 5 min hard expiry
+export const REPLAY_SET_LIMIT = 1000;    // FIFO eviction beyond this
+
+// ── stable serialization ───────────────────────────────────────────────────
+
+/**
+ * Deterministic JSON serializer: object keys sorted lexicographically at
+ * every level, no whitespace. Used as the HMAC pre-image so the Node-side
+ * and plugin-side implementations produce identical signatures.
+ */
+export function stableStringify(value) {
+  if (value === null || typeof value !== 'object') {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return '[' + value.map((v) => stableStringify(v)).join(',') + ']';
+  }
+  const keys = Object.keys(value).sort();
+  const parts = [];
+  for (const k of keys) {
+    const v = value[k];
+    if (v === undefined) continue; // mirror JSON.stringify behavior
+    parts.push(JSON.stringify(k) + ':' + stableStringify(v));
+  }
+  return '{' + parts.join(',') + '}';
+}
+
+// ── helpers ────────────────────────────────────────────────────────────────
+
+function computeHmac(secret, preimage) {
+  return crypto.createHmac('sha256', String(secret)).update(preimage).digest('hex');
+}
+
+function preimageOf(envelope) {
+  // HMAC binds the four schema fields. Order doesn't matter — stableStringify
+  // sorts keys — but be explicit so the contract is readable.
+  return stableStringify({
+    id: envelope.id,
+    payload: envelope.payload,
+    timestamp: envelope.timestamp,
+    type: envelope.type,
+  });
+}
+
+function timingSafeEqualHex(a, b) {
+  if (typeof a !== 'string' || typeof b !== 'string') return false;
+  if (a.length !== b.length) return false;
+  try {
+    return crypto.timingSafeEqual(Buffer.from(a, 'hex'), Buffer.from(b, 'hex'));
+  } catch {
+    return false;
+  }
+}
+
+// ── replay-protection set (in-memory, module-scoped) ──────────────────────
+
+const _seenIds = new Map(); // id → timestamp; insertion-ordered for FIFO eviction
+
+function recordSeen(id) {
+  if (_seenIds.has(id)) {
+    // refresh insertion order is not desired — keep original entry
+    return;
+  }
+  _seenIds.set(id, Date.now());
+  while (_seenIds.size > REPLAY_SET_LIMIT) {
+    const firstKey = _seenIds.keys().next().value;
+    _seenIds.delete(firstKey);
+  }
+}
+
+/** Test/diagnostics helper — clears the replay-protection set. */
+export function _resetReplaySet() {
+  _seenIds.clear();
+}
+
+/** Test/diagnostics helper — current replay-set size. */
+export function _replaySetSize() {
+  return _seenIds.size;
+}
+
+// ── public API ─────────────────────────────────────────────────────────────
+
+/**
+ * Build a signed envelope.
+ *
+ * @param {string} type    Verb, e.g. "selection.update".
+ * @param {object} payload Arbitrary serializable object.
+ * @param {string} secret  Shared secret (UTF-8 string).
+ * @returns {object}       Envelope ready for transport.
+ */
+export function createEnvelope(type, payload, secret) {
+  if (typeof type !== 'string' || type.length === 0) {
+    throw new TypeError('createEnvelope: type must be a non-empty string');
+  }
+  if (payload === null || typeof payload !== 'object') {
+    throw new TypeError('createEnvelope: payload must be an object');
+  }
+  if (typeof secret !== 'string' || secret.length === 0) {
+    throw new TypeError('createEnvelope: secret must be a non-empty string');
+  }
+  const envelope = {
+    id: crypto.randomUUID(),
+    type,
+    payload,
+    timestamp: Date.now(),
+  };
+  envelope.hmac = computeHmac(secret, preimageOf(envelope));
+  return envelope;
+}
+
+/**
+ * Verify a received envelope.
+ *
+ * @param {object} envelope
+ * @param {string} secret
+ * @param {{ now?: number }} [options] Optional clock override (testing).
+ * @returns {{ ok: true } | { ok: false, code: string, message?: string }}
+ */
+export function verifyEnvelope(envelope, secret, options = {}) {
+  if (envelope === null || typeof envelope !== 'object') {
+    return { ok: false, code: 'MALFORMED', message: 'envelope is not an object' };
+  }
+  const { id, type, payload, timestamp, hmac } = envelope;
+  if (typeof id !== 'string' || id.length === 0) {
+    return { ok: false, code: 'MALFORMED', message: 'missing id' };
+  }
+  if (typeof type !== 'string' || type.length === 0) {
+    return { ok: false, code: 'MALFORMED', message: 'missing type' };
+  }
+  if (payload === null || typeof payload !== 'object') {
+    return { ok: false, code: 'MALFORMED', message: 'missing or invalid payload' };
+  }
+  if (typeof timestamp !== 'number' || !Number.isFinite(timestamp)) {
+    return { ok: false, code: 'MALFORMED', message: 'missing or invalid timestamp' };
+  }
+  if (typeof hmac !== 'string' || hmac.length === 0) {
+    return { ok: false, code: 'MALFORMED', message: 'missing hmac' };
+  }
+  if (typeof secret !== 'string' || secret.length === 0) {
+    return { ok: false, code: 'MALFORMED', message: 'verifier secret must be non-empty string' };
+  }
+
+  const now = typeof options.now === 'number' ? options.now : Date.now();
+
+  // Future-skew check (timestamp claims to be too far in the future)
+  if (timestamp - now > CLOCK_SKEW_MS) {
+    return { ok: false, code: 'EXPIRED', message: 'timestamp is in the future beyond clock-skew tolerance' };
+  }
+  // Past expiry check (timestamp older than MAX_AGE_MS)
+  if (now - timestamp > MAX_AGE_MS) {
+    return { ok: false, code: 'EXPIRED', message: 'envelope older than max-age' };
+  }
+
+  // HMAC check
+  const expected = computeHmac(secret, preimageOf(envelope));
+  if (!timingSafeEqualHex(expected, hmac)) {
+    return { ok: false, code: 'HMAC_MISMATCH', message: 'hmac signature does not match' };
+  }
+
+  // Replay check — must come after HMAC (don't pollute the set with junk)
+  if (_seenIds.has(id)) {
+    return { ok: false, code: 'REPLAY', message: 'envelope id already seen' };
+  }
+  recordSeen(id);
+
+  return { ok: true };
+}
+
+export default { createEnvelope, verifyEnvelope, stableStringify };