AI-native design editor. Open-source Figma alternative.
Repo tooling, CI, and releases
Private tooling lives under tools/<role>/<domain>/{src,tests}; Steiger enforces the layout and kebab-case domain names. Every tool is a workspace named @open-pencil/<domain>-tools, listed literally in the root workspaces (the manifest schema rejects globs on purpose), so it can declare dependencies and run through bun --filter. bun run check:tools type-checks every tool through tools/tsconfig.json, reporting only files under tools/ as check:test-types does for tests (tools/checks/test-types/src/index.ts); bun run test:tools runs every tool with a test script. A tool imports its own files through its package.json imports alias (#ci/*, #release/*), other tools through their package name, and the docs site config through the shared #docs-config/* path.
| Role | Contract | Domains |
|---|---|---|
checks/ |
Read the tree and exit non-zero; never write inside the repository except an own baseline behind an explicit --write |
architecture, lint, i18n, secret-scan, type-shapes, docs, test-homes, package-quality |
generate/ |
Write generated files or artifacts, idempotently | brand, demo, emoji-metrics, tauri-menu, authoring-reference, visual-oracles, landing-posters |
release/ |
Build, verify, and publish packages and native artifacts | package-artifacts, release-packages |
ci/ |
Consumed by workflows: path classification and gate policy, container images, the review-guidance bot | policy, images, pr-review-guidance |
dev/ |
Test running, benchmarks, and local services for humans | unit-tests, navigation-benchmark, dev-server, cloud |
- Nothing under
generate/orrelease/runs frombun run checkexcept through a check entrypoint;generate/authoring-referencekeeps itscheck.tsbesidegenerate.tsuntil it splits. - Resolve the workspace with
resolveWorkspaceRootfrom@open-pencil/package-artifacts-tools, not parent-directory traversal. Keep sibling imports relative. checks/test-homesownsengine-baseline.txtandcheck:test-homes;dev/unit-testsowns the shard map and runner (tests/AGENTS.md).- No
scripts/entrypoints: rootpackage.jsonscripts call tool files directly.
CI
.github/workflows/ci.ymlandheavy-tests.ymldefine validation gates. PR CI always classifies changed paths throughtools/ci/policy/src/policy.ts: root docs, package READMEs, everyAGENTS.md,packages/docsMarkdown and assets, and skill Markdown are docs-only; runtime prompt Markdown, executable examples, configuration, and unknown paths require code validation.- Docs-only changes run documentation integrity and the docs build; everything else runs the full suites (
tools/ci/policy/src/policy.ts). - The Cloud suites run when a change touches what
packages/cloudis built from, derived from its workspace dependencies (tools/ci/policy/src/cloud-inputs.ts). - The aggregate
CI resultgate requires successful classification and every applicable job; failures, cancellations, and unexpected skips cannot pass (tools/ci/policy/src/gate.ts). - Do not restore workflow-level path filtering on required CI: a required check whose workflow never runs stays pending and blocks the merge (
.github/workflows/ci.yml). commitlint.config.tsenforces commit structure in the Commit messages job; the separate PR title workflow validates titles. Preserve theRelease vX.Y.ZandRelease vX.Y.Z-beta.Nexception, including the(#N)the merge queue appends, and product casing when changing rules; the known AI co-author check does not rewrite base history. Gate policy lives intools/ci/policy/src/policy.ts.tools/ci/policyruns right after Bun is set up, before any install, so it imports only Node built-ins;oxlint.jsonswitchesopen-pencil/prefer-es-toolkitoff there. Other CI tools install their workspace first, aspr-review-guidance.ymldoes through.github/actions/setup-bun.- Required checks must also run on
merge_group, the merge queue's event; read base and head frommerge_group.base_sha/head_shathere (ci.yml,pr-title.yml). - Path classification measures a pull request from its merge commit's first parent, the base as it is now;
pull_request.base.shalags when the base moves and would count the base's newer commits as the pull request's (tools/ci/policy/tests/classify.test.ts). - A passing pull request run records the tree it tested as the
CI verified treestatus on the PR head; a merge queue commit with that exact tree is classifiedverifiedand runs only the always-on checks. Any other tree, including a group with other PRs ahead, gets the full run (tools/ci/policy/src/verified-tree/). - The app production workflow runs on
v*tags, and the docs workflow when a release is published, since the download page reads GitHub's releases at build time; both also run onworkflow_dispatch, never on ordinarymasterpushes.build.ymlchecks the tooling out under.pipeline/and runstools/release/release-packagesfrom there.
Releases
- Update versions in the root and publishable package manifests plus
desktop/tauri.conf.jsonanddesktop/Cargo.toml; runbun run changelog:assemble, curateUnreleased(bun run check:changelog --release), and move it into## x.y.z — YYYY-MM-DD; commitRelease vX.Y.Z; tag and pushvX.Y.Z. A pre-release usesX.Y.Z-beta.Nthroughout. .github/workflows/build.ymlis the source of truth:v*tags (or dispatches for an immutable stable tag) build shared frontend/package outputs once, build signed desktop artifacts in parallel, verify and attest one complete same-run artifact set, publish npm packages, and replace the draft release assets using the exact changelog section. Policy, provenance, and recovery:tools/release/release-packages/README.md..github/workflows/chromium.ymlbuilds OpenPencil Chromium (Tauri v3 with CEF), a flavor of a release, by hand frombuild/tauri-v3once that branch has merged exactly the release tag, and adds its macOS bundles andlatest-chromium.json, its update feed, to that release after every macOS build succeeds; stable tooling and the download page skip those files (isChromiumAsset). Its steps live intools/release/release-packages/src/chromium, beside the stable release scripts they reuse.- Public workspace packages are discovered by the package-artifacts catalog. Bun source exports require the complete
srcdirectory in package contents; Node exports usedist. Release preparation must preserve resolution maps. Prepared publish directories receive the rootLICENSEwhen a package has none of its own, and every package needs aREADME.mdbecause npm renders it. Publishing uses prepared npm tarballs verified through the shared Node/Bun consumer checks; never publish package directories manually.test:packagesfirst runs the packaging guards intools/checks/package-quality/src/smoke/guards.ts: fixture manifests packed with the realnpm packthat must trip the tarball inspector and the Node/Bun consumer checks before those checks vouch for real packages. - Pre-releases are only
vX.Y.Z-beta.N: they publish to npm'snextdist-tag, draft as a GitHub pre-release that is never latest, install on Windows as MSIX.Y.Z.N, and skip the app and docs deploys (tools/release/release-packages/src/version.ts). - A beta's changelog section opens with the pre-release note and lists changes since the previous beta. The final
X.Y.Zreplaces its beta sections with one section written against the previous stable release, opened by a short highlights paragraph, with fixes to new features folded into their bullets; the GitHub pre-releases keep the beta notes (CHANGELOG.md). - Official builds (
VITE_OPENPENCIL_FEEDBACK=on) emit hidden source maps;app.ymland thebuild.ymlfrontend job inject PostHog chunk IDs, upload the maps to PostHog error tracking as releaseopenpencil@<version>, and strip them fromdist, andbuild.ymlattaches them asOpenPencil_<version>_sourcemaps.tar.gz. Both need thePOSTHOG_CLI_API_KEYsecret, a personal key with error tracking write and organization read (tools/release/release-packages/src/sourcemaps/publish.ts). - Ensure Tauri and Apple signing/notarization secrets are configured. Verify the draft title, body, and artifacts, then publish. Release titles are exactly the tag (
vX.Y.Z) without a product-name prefix. - Homebrew's
openpencilcask is managed upstream: BrewTestBot proposes bumps and Homebrew merges them. Check the upstream cask PR after publication; do not push to the archived custom tap or add bump automation. Users install the app withbrew install --cask openpenciland the CLI through npm or Bun.
Demo document
The /demo document is a tour of eight chapters on one page, each a section stacked top to bottom, built from tools/generate/demo/src/document/: theme.ts (the Theme and App chrome collections, each with a Dark and a Light mode that src/app/demo/theme.ts switches by name to follow the app's theme; every color in the tour, icons included, is bound to them), callout.tsx (the Tip component every chapter instances, whose Where slot each fills with a piece of the app from chrome.tsx, drawn to the dark theme's tokens with the target ringed), player/ (the player card, its artwork slot, and its controls with behaviours), and one file per chapter under chapters/, laid out by chapters/chapter.ts as numeral, heading, subject, and tip, with each section's and subject's name from chapters/names.ts, which hosts outside the app such as the docs landing import from @open-pencil/demo-tools/chapters; src/app/demo/viewport.ts opens the tour on the first chapter. It renders design JSX through document/icons.ts, which serves Lucide from the bundled icon JSON so the build needs no Iconify API, and writes the ignored public/demo.fig, which the app opens like any .fig file; it is never generated in the browser. ensureDemoDocument runs from vite.config.ts, rebuilds only when its inputs' fingerprint changes, and runs the build in Bun; bun run generate:demo forces it. A chapter that needs something new from the engine adds that package's src to the fingerprint in tools/generate/demo/src/ensure.ts. Shader fills get their still frames from src/shaders/stills.ts, which draws each preset in the Playwright Chromium with WebGPU, at the size and in the encoding the editor uses (shaderFramePixels and shaderFrameEncoding from scene-graph) (bunx playwright install chromium locally; the deploy and preview workflows install it); without the browser the build warns and the editor draws the frames when the demo opens.
Landing posters
tools/generate/landing-posters/ captures WebP stills of every docs landing stage, per locale, theme, and layout, from a production docs build served locally in headless Chromium with software WebGL. build:production in packages/docs runs it after vitepress build; it reuses .cache/landing-posters/<fingerprint> when the inputs in src/fingerprint.ts are unchanged and copies the stills into dist, and generate:landing-posters forces a capture. The docs deploy workflow spreads the capture over runners: one job runs build:site, four run the generator with --shard i/4, and the deploy job gathers their stills and runs it with --assemble, which fails on any missing still; dispatching it with dry-run builds and captures without deploying and keeps the stills as an artifact. A stage that starts depending on a new source tree adds it to LANDING_POSTER_INPUTS.
Brand assets
Canonical artwork lives in assets/brand/ (main mark and optical micro master; see its README). tools/generate/brand/ derives web, docs, and native icons with RealFaviconGenerator and Tauri; generated assets are ignored, not committed. Vite and VitePress configs prepare their own targets, and Tauri dev/build hooks prepare native icons.