@vyriy/ssg 0.8.8 → 0.8.9

package/AGENTS.md

@@ -1,102 +1,159 @@
-# Project Agent Guide
+# Vyriy Package Agent Guide
 
-This repository follows a calm engineering style: changes should be explicit, reusable, typed, documented, tested, and easy to reason about.
+This guide applies to everything under `packages/*`.
 
-Use this guide as the default behavior for AI agents and contributors working in this repository. Prefer local package conventions when they are more specific than this document.
+Always read the root `AGENTS.md` first for current project direction, then use this package guide as the stricter local contract for package work. If the root guide gains new package-relevant knowledge, sync it here in the same change or in the next package-touching change so this file does not drift behind.
 
-## Core Principles
+## Package Principles
 
-- Prefer simple modules over clever frameworks or hidden conventions.
-- Keep package and project boundaries explicit.
-- Avoid project-specific coupling in reusable code.
-- Extract only proven reusable behavior.
-- Keep public APIs small, typed, documented, and stable.
-- Prefer SSR-friendly and SSG-friendly code paths when working with frontend or shared code.
-- Keep integrations replaceable and avoid hard coupling to a CMS, framework, vendor, or runtime host.
-- Prefer infrastructure assumptions that are easy to deploy, observe, and replace.
+- Keep packages small, explicit, typed, documented, tested, and easy to reason about.
+- Prefer calm reusable contracts over project-specific shortcuts.
+- Keep every package responsible for one clear capability or closely related capability group.
+- Keep public APIs small and intentional.
+- Prefer SSR-friendly, SSG-friendly, and runtime-agnostic code paths.
+- Avoid hidden framework, CMS, browser, filesystem, network, or cloud assumptions unless they are the package contract.
+- Add packages only when they reduce real complexity, clarify boundaries, or improve reuse.
 - Prefer the option that is simpler to explain, easier to evolve, and calmer to maintain.
 
-## File Shape
+## Standard Package Shape
 
-- Prefer one exported runtime method, component, helper, or class per production file when it stays readable.
+Use `packages/pause` as the default structural template for ordinary runtime packages.
+
+Expected files for a typical package:
+
+- `README.md`
+- `doc.mdx`
+- `index.ts`
+- `index.test.ts` when public re-exports need coverage
+- `package.json`
+- `<package>.ts`
+- `<package>.test.ts`
+- `types.ts` when public shared types are part of the package contract
+
+Package-local build configs are not the default. Add them only when a package has a real special-purpose build shape.
+
+## File Responsibility
+
+- Prefer one exported runtime method, component, helper, class, or factory per production file when it stays readable.
+- Keep types in `types.ts` or focused type files when they are public, reused, or make runtime code noisy.
+- Keep implementation code separate from type-only contracts when that improves readability or reuse.
 - Prefer one matching test file per production file, for example `feature.ts` and `feature.test.ts`.
 - Use focused folders when behavior naturally splits into several related files.
+- Inside focused folders, prefer short file names because the folder path already carries part of the meaning.
 - Keep `index.ts` as a public re-export surface only. Do not place implementation logic in it.
+- Keep constants near the code that owns them unless they are shared, clarify intent, or reduce repeated noise.
+- Avoid exporting internal helpers only to make tests easier.
+
+## Imports And Exports
+
 - Use relative import and export specifiers that match the package module style.
 - Use `.js` relative specifiers in TypeScript source for ESM/NodeNext packages.
-- Add `types.ts` when public shared types are part of the package contract.
-- Keep constants near the code that owns them unless they are shared or clarify repeated behavior.
+- Re-export every public runtime export from the package public entry point.
+- Re-export public types with `export type`.
+- Add or update `index.test.ts` when public exports change.
+- Do not hand-maintain package `exports` maps in source manifests unless the package has a real custom publishing need.
 
-## Public Surface
+Example:
 
-- Every new public export must be re-exported from the package or module public entry point.
-- Add or update public-surface tests when exports change.
-- Add JSDoc for public exports when behavior, parameters, return values, or usage expectations need explanation.
-- Avoid exporting internal helpers only to make tests easier.
-- Do not hand-maintain package `exports` maps unless the project has a real custom publishing need.
+```ts
+export * from './feature.js';
+export type * from './types.js';
+```
+
+## Package Manifest
+
+Keep source `package.json` files minimal and let `build:dist` generate publishing metadata where possible.
+
+Typical runtime package fields:
+
+- `"private": true`
+- `"type": "module"`
+- `"engines": { "node": ">=24.0.0" }`
+- `"main": "index.js"` when the package has a runtime entry
+- runtime dependencies only when package source imports them at runtime
+
+## Documentation Is Required
 
-## Tests
+Documentation must move with code. Do not finish a package change while docs describe a different API than the implementation.
 
-- Cover public behavior and meaningful edge cases.
+- Every package must have a concise, usage-oriented `README.md`.
+- Every ordinary package should have `doc.mdx`, normally wrapping the package README in the Storybook/docs style used by `packages/pause/doc.mdx`.
+- Start package READMEs with `# @vyriy/<package>`.
+- Document real public exports, supported options, behavior expectations, and examples that actually work.
+- Update README examples whenever imports, parameters, return values, configuration, or behavior changes.
+- Keep `doc.mdx` aligned with the README and package title when packages are added, renamed, or reorganized.
+- Add or update JSDoc for public exports when behavior, parameters, return values, errors, side effects, or usage expectations need explanation.
+- For component packages, include visual documentation, stories, or examples for supported states, variants, and interaction states.
+- Avoid broad architecture essays in package READMEs; keep architectural direction in root-level docs unless it is necessary to use the package.
+
+## Tests Are Required
+
+Tests should protect public behavior and meaningful regression risk.
+
+- Add or update Jest tests for changed public behavior, public exports, and meaningful edge cases.
+- Add a real test immediately for new packages. If behavior is not finalized, add a valid placeholder test with a clear public API expectation.
 - Prefer behavior-focused tests over private implementation lock-in.
-- Keep tests deterministic.
-- Avoid real network, filesystem, timers, browser, or cloud dependencies unless the behavior specifically requires them.
+- Keep tests deterministic and avoid real network, timers, browser, filesystem, or cloud dependencies unless that dependency is the behavior under test.
 - When mocking modules, install mocks before loading the module under test.
-- Use focused validation when changing behavior.
+- Use `@jest/globals` in Jest tests.
+- Use `--coverage=false` for focused behavioral regression runs when global coverage thresholds would obscure the result.
 
-Example validation commands:
+Typical package test naming:
 
-```bash
-yarn test
-```
+- `<package>.test.ts` for single-file packages
+- `<feature>.test.ts` for multi-entry packages
+- `index.test.ts` for public re-export coverage
 
-For workspaces, prefer the project convention, for example:
+## Quality Gate
 
-```bash
-yarn workspace <package-name> test
-```
+Before finishing package work, keep the package surface synchronized and run focused validation.
+
+Required sync checks:
 
-For Jest-based packages, focused validation may look like:
+- implementation matches public types
+- public exports are updated
+- public-surface tests are updated when exports change
+- unit tests cover new or changed behavior
+- `README.md` matches the actual API and examples
+- `doc.mdx` exists and points at the correct README/title for ordinary packages
+- JSDoc is updated for public API changes that need explanation
+- source manifests stay minimal and accurate
+- `.js` relative specifiers are used where required
+- no unrelated refactors, formatting churn, or generated artifacts are included
+
+Preferred validation commands:
 
 ```bash
-yarn jest packages/<package> --runInBand --coverage=false
+yarn tsc --pretty false
+yarn eslint <changed files or package>
+yarn prettier --check <changed files or package>
+yarn jest <changed tests or package> --runInBand --coverage=false
 ```
 
-## Documentation
+Also run `yarn build:dist` for package export, manifest, build-shape, or generated-dist behavior changes. After larger package or library changes, prefer building the affected library/package as an additional confidence check.
+
+If a required validation command cannot be run, state why and report the remaining risk.
 
-- Keep `README.md` concise and usage-oriented.
-- Start package READMEs with `# <package>`.
-- Document real public exports, supported options, and examples that actually work.
-- Update docs when public behavior changes.
-- Keep generated docs wrappers, such as `doc.mdx`, aligned with the README when the project uses them.
-- For component packages, include visual documentation or stories for supported states and common usage.
+## New Package Checklist
 
-## Components
+When creating a new workspace package `@vyriy/<package>`:
 
-- Prefer lightweight React components with TypeScript when working in React packages.
-- Keep components SSR-friendly and avoid browser globals during render.
-- Prefer composable props and predictable ergonomics.
-- Put each public component in its own file with a matching test.
-- Add stories or examples when a component has visual states, variants, or interaction states.
-- Keep styling explicit and reusable. Avoid hidden theme assumptions unless they are part of the package contract.
+1. Create `packages/<package>`.
+2. Mirror `packages/pause` unless the package purpose clearly requires a different shape.
+3. Replace `pause` references with the new package name, exported symbols, types, metadata, paths, README, and docs title.
+4. Keep implementation, public types, tests, README, `doc.mdx`, public exports, and manifest in sync from the first change.
+5. Keep `.js` relative import/export specifiers.
+6. Add a real test immediately, or a valid placeholder test with a clear public API expectation when behavior is not finalized.
+7. Keep source `package.json` minimal and let `build:dist` generate publish metadata.
+8. Run relevant type, lint, format, test, and build checks.
 
 ## Change Discipline
 
-- Keep changes scoped to the requested behavior.
-- Avoid unrelated refactors and metadata churn.
-- Sync implementation, tests, docs, examples, and public re-exports together.
-- Do not introduce new dependencies unless they clearly reduce complexity or are already part of the project direction.
+- Keep changes scoped to the requested package behavior.
 - Prefer small, reviewable changes over broad rewrites.
-- Preserve existing conventions unless there is a clear reason to change them.
-
-## Before Finishing
-
-Check that the change is complete:
-
-- Public exports are updated.
-- Public-surface tests are updated when exports change.
-- Matching unit tests exist for new behavior.
-- README examples still match the real API.
-- Visual docs, stories, or examples are updated for visible component behavior.
-- TypeScript imports follow the package module style.
-- No unrelated files, formatting churn, or generated artifacts were changed.
+- Split multi-responsibility files into cohesive modules when it makes behavior easier to understand, test, or reuse.
+- Avoid abstraction for its own sake.
+- Do not introduce new dependencies unless they clearly reduce complexity or are already part of the project direction.
+- Preserve existing package conventions unless there is a clear reason to change them.
+- Never leave package docs, tests, exports, or public types behind the implementation.
+- When you learn something package-relevant while working, update the nearest durable guide or docs so future package work starts from that knowledge.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vyriy/ssg",
-  "version": "0.8.8",
+  "version": "0.8.9",
   "description": "Static Markdown site generator for Vyriy projects.",
   "homepage": "https://vyriy.dev/docs/ssg/",
   "type": "module",
@@ -10,7 +10,7 @@
   },
   "dependencies": {
     "@types/react": "^19.2.17",
-    "@vyriy/render": "0.8.8",
+    "@vyriy/render": "0.8.9",
     "minisearch": "^7.2.0",
     "react": "^19.2.7",
     "react-markdown": "^10.1.0",