0.3.55 • Published 4h ago

@pie-players/pie-section-player-tools-shared

Licence

MIT

Version

0.3.55

Deps

Size

109 kB

Vulns

Weekly

Stars

Summary Dependency Versions

pie-players

PIE players and assessment toolkit with Bun + TypeScript + Svelte 5.

Docs app: apps/docs Examples app: apps/section-demos

Quick Start

bun install
bun run dev:section -- --rebuild   # First section-demo run (builds package dist outputs)
bun run dev:section                # Section demos (daily run)
bun run dev:docs                   # Docs site

Development

bun run dev      # Turbo dev for section-demos (see package.json "dev")
bun run build    # Build publishable packages + tools (excludes apps)
bun run typecheck
bun run test
bun run format   # Format (Biome)

Demo apps resolve publishable packages through dist/ (and section-demos uses explicit Vite aliases for many tools). See Demo workspace resolution.

Consumer Import Rules

When consuming PIE web components from apps or other packages:

Import custom-element registration entrypoints (for example @pie-players/pie-assessment-toolkit/components/item-toolbar-element), not raw package .svelte component files.
Do not import package source paths like @pie-players/<pkg>/src/... from consumers.
Do not use cross-package ?customElement imports.
Keep runtime package exports pointing to built dist artifacts.

Boundary checks:

bun run check:source-exports
bun run check:consumer-boundaries
bun run check:custom-elements

All publishable @pie-players/* packages are released with a fixed (lockstep) version. At any published version, every package in the suite carries that same version number — there is no per-package version drift.

What this means for consumers

Pick one @pie-players/* version and update every @pie-players/* dependency in your app to that version. The suite is tested and published as a cohesive unit at that version.
You will never need to reason about a compatibility matrix across @pie-players/* packages. If two @pie-players/* packages report the same version, they are designed and tested to work together.
While the project remains on the pre-1.0 0.x.y line, every release is a patch release across all publishable packages, including ones whose source did not change. This is expected — it is the cost of the lockstep guarantee above.

Why fixed versioning

The publishable packages in this repo (players, tools, TTS servers, theming, toolkits) form a single cohesive player framework. Internal contracts cross package boundaries (element registration, theme tokens, tool coordination, session/session-state shape), so consumers almost always adopt the suite together rather than piecemeal. Fixed versioning removes a category of compatibility bugs at the cost of more churn on unchanged packages per release.

How it is enforced

Changesets' fixed block in .changeset/config.json lists every publishable package.
scripts/check-fixed-versioning.mjs runs as part of bun run verify:publish and blocks publish if any publishable package has drifted.
Release prep always covers every publishable package — see AGENTS.md and docs/setup/publishing.md.

Releasing From Workspace

This monorepo keeps internal dependencies as workspace:* during development.

The canonical local release command is bun run release:with-version. It creates the temporary all-packages patch changeset, rewrites workspace ranges to concrete package versions for publish, runs preflight checks/tests, publishes, then restores the original workspace ranges. This avoids leaking workspace:* into npm metadata while keeping local development ergonomics unchanged.

Local publishing uses the codebase and branch currently checked out. Confirm the current branch and working tree state before publishing; do not switch to a different branch or use the GitHub workflow unless that is explicitly requested.

Before release merges/publishes, run:

bun run verify:publish

Manual patch-only publish flow (matches CI gates):

bun run release:with-version

release:with-version creates a temporary all-packages patch changeset, runs preflight checks/tests, then publishes. Merges to master also auto-generate a temporary patch changeset when needed for release PR prep.

Registry switching (CodeArtifact vs npmjs)

Use npmjs for publishing @pie-players/*, and switch back to CodeArtifact for private consumer installs when needed.

# one command on npmjs (preferred)
NPM_CONFIG_REGISTRY=https://registry.npmjs.org npm whoami

# publish path on npmjs
NPM_CONFIG_REGISTRY=https://registry.npmjs.org bun run release:with-version

# set current registry to npmjs
npm config set registry https://registry.npmjs.org/

# set current registry back to CodeArtifact
npm config set registry https://renaissance-112784725199.d.codeartifact.us-east-1.amazonaws.com/npm/npm-rgp/

Release Labels

Use release labels to tag a coordinated release wave without forcing lockstep package versions.

bun run release:label                # Create annotated tag (default: pie-players-YYYY.MM.DD)
bun run release:label -- --label players-2026.02
bun run release:label:push           # Create and push tag to origin

Packages

Interactive Players: pie-item-player Print Player: print-player - Item-level print rendering for production use Tools: calculator, graph, ruler, protractor, annotation-toolbar, color-scheme, periodic-table Shared: players-shared, assessment-toolkit