{"_id":"@blcklab/create-principia","name":"@blcklab/create-principia","dist-tags":{"latest":"0.18.0"},"versions":{"0.18.0":{"name":"@blcklab/create-principia","version":"0.18.0","description":"Zero-dependency initializer for Principia documentation and convention-based modular playgrounds.","type":"module","bin":{"create-principia":"bin/create-principia.mjs"},"scripts":{"test":"node ./test.mjs","pack:check":"npm pack --dry-run","check":"npm test && npm run pack:check"},"keywords":["principia","documentation","markdown","github","playground","initializer"],"repository":{"type":"git","url":"git+https://github.com/blcklab/create-principia.git"},"bugs":{"url":"https://github.com/blcklab/create-principia/issues"},"homepage":"https://github.com/blcklab/create-principia#readme","license":"MIT","engines":{"node":">=20.11.0"},"publishConfig":{"access":"public"},"_id":"@blcklab/create-principia@0.18.0","gitHead":"ce6a224419919608f0c170fc103cdc737f481d3d","_nodeVersion":"22.23.2","_npmVersion":"10.9.8","dist":{"integrity":"sha512-Y2FG1Ge4xQ41ADFdZB94Cqzavx8+HlFcDRmbakinVrJy2s30hA769Q+/7XAcIwiN8Jkf+RKILAKKQS1IQFAWLQ==","shasum":"dd26eb7f1c6e622e1896f266024eaa30eb0b7632","tarball":"https://registry.npmjs.org/@blcklab/create-principia/-/create-principia-0.18.0.tgz","fileCount":11,"unpackedSize":61726,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIApK5xt0NiQi6dboHytfq0CanKCzWrWPr800Cb9r6bt6AiAuksYbOSSwUIyx36IA256qbABO5tqYMNzCqxQLE8S1+Q=="}]},"_npmUser":{"name":"okarin_lab","email":"avelurs.billy@gmail.com"},"directories":{},"maintainers":[{"name":"okarin_lab","email":"avelurs.billy@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/create-principia_0.18.0_1787986736329_0.5360341990048263"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-29T06:58:56.184Z","0.18.0":"2026-08-29T06:58:56.470Z","modified":"2026-08-29T06:58:56.706Z"},"maintainers":[{"name":"okarin_lab","email":"avelurs.billy@gmail.com"}],"description":"Zero-dependency initializer for Principia documentation and convention-based modular playgrounds.","homepage":"https://github.com/blcklab/create-principia#readme","keywords":["principia","documentation","markdown","github","playground","initializer"],"repository":{"type":"git","url":"git+https://github.com/blcklab/create-principia.git"},"bugs":{"url":"https://github.com/blcklab/create-principia/issues"},"license":"MIT","readme":"# Create Principia\n\nA zero-dependency initializer that adds Principia documentation, convention-based playgrounds, and new examples to an existing repository.\n\n## Fastest setup\n\nRun this inside a JavaScript or CSS library:\n\n```bash\nnpm create @blcklab/principia@latest -- . --playground auto\n```\n\nThe initializer reads the local `package.json` and detects:\n\n- npm package name\n- current package version\n- CSS, browser ESM, or explicit interactive DOM adapter\n- published stylesheet or module entry\n- a safe plugin id and display label\n\nIt does not add a dependency to the target project. Generated code opens in Principia’s lightweight Yuirinx-highlighted Playground editor.\n\n## Folder-based examples\n\nA CSS package generates normal editable files:\n\n```text\n.principia/\n├── playground.json\n└── playground/\n    └── <plugin>/\n        └── examples/\n            └── starter/\n                ├── index.html\n                └── style.css\n```\n\nA browser module package generates:\n\n```text\n.principia/\n├── playground.json\n└── playground/\n    └── <plugin>/\n        └── examples/\n            └── starter/\n                └── main.js\n```\n\n\nAn interactive DOM package created with `--playground dom` generates:\n\n```text\n.principia/\n├── playground.json\n└── playground/\n    └── <plugin>/\n        └── examples/\n            └── starter/\n                ├── index.html\n                ├── style.css\n                └── main.js\n```\n\nAdd another example with the initializer:\n\n```bash\nnpm create @blcklab/principia@latest -- . --add-example buttons\n```\n\nFor sidebar metadata:\n\n```bash\nnpm create @blcklab/principia@latest -- . \\\n  --add-example buttons \\\n  --group Components \\\n  --order 20\n```\n\nThe command detects the existing plugin adapter. CSS examples receive only `index.html`; `style.css` remains optional. Module examples receive `main.js`. DOM examples receive `index.html`, `style.css`, and `main.js`. Principia discovers immediate child directories automatically and shows multiple examples in a desktop sidebar or mobile drawer. Each example has a shareable URL.\n\nOptional navigation metadata can be added to `playground.json` without repeating file paths:\n\n```json\n{\n  \"examples\": [\n    { \"id\": \"starter\", \"label\": \"Starter\", \"group\": \"Getting Started\", \"order\": 10 },\n    { \"id\": \"buttons\", \"label\": \"Buttons\", \"group\": \"Components\", \"order\": 20 }\n  ]\n}\n```\n\nOne-example plugins stay full-width and do not show unnecessary navigation.\n\n### CSS conventions\n\n```text\nexample-name/\n├── index.html    required\n├── style.css     optional\n└── example.json  optional metadata\n```\n\n### Module conventions\n\n```text\nexample-name/\n├── main.js       required\n├── controls.json optional generated controls\n└── example.json  optional mode/output metadata\n```\n\n\n### DOM conventions\n\n```text\nexample-name/\n├── index.html    required body fragment\n├── main.js       required run({ module, inputs }) export\n├── style.css     optional\n├── controls.json optional\n└── example.json  optional viewport and presentation metadata\n```\n\nDOM examples run in a fresh `sandbox=\"allow-scripts\"` opaque-origin iframe on every Run and Reset. They can use the preview's `window` and `document`, but cannot access Principia's parent DOM or storage, open popups, navigate the parent, submit forms, download files, or make arbitrary network requests. The package API is injected as `module`; editable code does not use bare imports.\n\n## Try examples from documentation\n\nWhen the initializer creates new starter documentation and a Playground together, the generated `docs/index.md` includes a code fence that runs the exact visible snippet:\n\n````markdown\n```html playground\n<section class=\"container section\">...</section>\n```\n````\n\nPrincipia adds **Try in Playground** beside Copy. The exact snippet opens in a focused editor and preview drawer without navigating away from the documentation. Existing documentation is never rewritten; add the bare `playground` marker manually to any supported HTML, CSS, or JavaScript fence you want readers to test.\n\n## Safe existing-project behavior\n\nThe initializer validates package and Playground inputs before writing files. Existing JSON configuration is merged only when it is valid; malformed `principia.config.json` files stop the command with a non-zero exit instead of leaving a partially generated setup. Generated JSON files use atomic replacement.\n\n## Existing documentation\n\nThe initializer safely adds the Playground entry to an existing `principia.config.json` without replacing its documentation settings:\n\n```bash\nnpm create @blcklab/principia@latest -- . --playground auto\n```\n\nWhen an existing Principia config is found, starter Markdown files are not created.\n\nFor repositories created before the Principia rename, the initializer also recognizes `scriptoria.config.json` and `.scriptoria/playground.json`. It updates those legacy files in place instead of creating duplicate Principia configuration. New repositories always use the Principia filenames.\n\n## Explicit adapter\n\n```bash\nnpm create @blcklab/principia@latest -- . --playground css\nnpm create @blcklab/principia@latest -- . --playground module\nnpm create @blcklab/principia@latest -- . --playground dom\n```\n\nOverride detected package metadata:\n\n```bash\nnpm create @blcklab/principia@latest -- . \\\n  --playground css \\\n  --package @blcklab/edencss \\\n  --package-version 1.0.1 \\\n  --asset-path dist/edencss.css\n```\n\n## npm version behavior\n\nThe local exact `package.json#version` is used by default for reproducible examples.\n\nTo always follow the npm `latest` dist-tag:\n\n```bash\nnpm create @blcklab/principia@latest -- . \\\n  --playground auto \\\n  --package-version latest\n```\n\nPrincipia accepts exact semantic versions and `latest`. Version ranges remain rejected.\n\n### Synchronize an existing manifest before release\n\nAfter updating the local package version, synchronize every Playground plugin that uses the same npm package:\n\n```bash\nnpm create @blcklab/principia@latest -- . --sync-package-version\n```\n\nThe command reads `package.json#name` and `package.json#version`, updates only matching `asset.version` fields in `.principia/playground.json`, and writes the manifest atomically.\n\nOverride the value explicitly when needed:\n\n```bash\nnpm create @blcklab/principia@latest -- . \\\n  --sync-package-version \\\n  --package-version latest\n```\n\nFor manifests containing several unrelated packages, select one plugin:\n\n```bash\nnpm create @blcklab/principia@latest -- . \\\n  --sync-package-version \\\n  --plugin-id secondary-plugin \\\n  --package-version 2.1.0\n```\n\nRecommended release flow:\n\n```bash\nnpm version 2.1.0 --no-git-tag-version\nnpm create @blcklab/principia@latest -- . --sync-package-version\ngit add package.json package-lock.json .principia/playground.json\ngit commit -m \"release: v2.1.0\"\ngit tag v2.1.0\ngit push origin main --tags\n```\n\nPrincipia's documentation version selector then loads the manifest from `v2.1.0`, which points to npm package `2.1.0`.\n\n## Module layout\n\nThe default folder-based module example opens `main.js` in editable mode.\n\n```bash\nnpm create @blcklab/principia@latest -- . \\\n  --playground module \\\n  --module-mode hybrid\n```\n\nUse read-only code:\n\n```bash\nnpm create @blcklab/principia@latest -- . \\\n  --playground module \\\n  --read-only-code\n```\n\nNon-default mode settings are stored in the example folder’s optional `example.json`.\n\n## Documentation only\n\n```bash\nnpm create @blcklab/principia@latest -- .\n```\n\nThis creates a small automatic-navigation configuration and starter Markdown under `docs/`.\n\n## Default documentation theme\n\nNew configurations include the core `principia` theme:\n\n```json\n{\n  \"appearance\": {\n    \"theme\": \"principia\"\n  }\n}\n```\n\nChoose a premium Kireix preset while generating the configuration:\n\n```bash\nnpm create @blcklab/principia@latest -- . --theme kireix-aurora\n```\n\nShow all first-party ids:\n\n```bash\nnpm create @blcklab/principia@latest -- --list-themes\n```\n\nCore ids are `principia`, `graphite`, `ocean`, and `forest`. Premium Kireix ids begin with `kireix` and require the Principia deployment to install and register `@blcklab/kireix`.\n\nFor an existing valid configuration, `--theme kireix-verdant` updates only `appearance.theme` and preserves the remaining documentation and Playground settings. Without an explicit `--theme`, existing theme settings are left untouched.\n\nRemote URLs and package names are not accepted as theme ids. Repository configuration selects only a theme already registered by the Principia host.\n\n## Other options\n\n```bash\n# Select a premium Kireix theme\nnpm create @blcklab/principia@latest -- . --theme kireix-oceanic\n\n# Custom docs folder\nnpm create @blcklab/principia@latest -- . --root guide\n\n# Multi-root docs\nnpm create @blcklab/principia@latest -- . --roots docs,notes,changelog\n\n# Custom examples location\nnpm create @blcklab/principia@latest -- . \\\n  --playground auto \\\n  --examples-root examples/playground\n\n# Local schemas\nnpm create @blcklab/principia@latest -- . \\\n  --schema-base http://localhost:5173/schemas/v0.17\n\n# Full option list\nnpx @blcklab/create-principia@latest --help\n```\n\n## Hosted schemas\n\nGenerated configuration uses:\n\n```text\nhttps://raw.githubusercontent.com/blcklab/principia/main/public/schemas/v0.22/principia.schema.json\nhttps://raw.githubusercontent.com/blcklab/principia/main/public/schemas/v0.22/playground.schema.json\n```\n\n`$schema` is only an editor hint. Principia performs runtime validation independently.\n\n## Safety\n\n- Existing example files are skipped unless `--force` is supplied.\n- Existing Principia documentation settings are preserved.\n- Only the trusted built-in `css`, `module`, and `dom` adapters are generated.\n- Exact npm versions are the default.\n- `latest` must be selected explicitly.\n- Version ranges and arbitrary adapter URLs are rejected.\n- No runtime dependency is added to the target repository.\n\n## Scaffold secure HTML module output\n\nFor packages that return static visual HTML:\n\n```bash\nnpm create @blcklab/principia@latest -- . \\\n  --playground module \\\n  --output html \\\n  --output-field html\n```\n\nThis writes output metadata on the generated manifest example and creates a browser-safe starter runner that returns an HTML field plus structured data. The Principia host sanitizes the HTML and renders it only in a dedicated no-script iframe.\n\nAdd another HTML example later:\n\n```bash\nnpm create @blcklab/principia@latest -- . \\\n  --add-example colored-ascii \\\n  --plugin-id sumijs \\\n  --output html \\\n  --output-field html\n```\n\n`--output-field` accepts one top-level property name. It does not support nested dot paths. HTML scaffolding is available only for module adapters.\n\n\n## Universal runtime imports\n\nAdd an additional browser ESM package to an existing module or DOM plugin:\n\n```bash\nnpm create @blcklab/principia@latest -- . \\\n  --add-import renderer \\\n  --import-package @blcklab/renderer \\\n  --import-version 1.2.0 \\\n  --import-path dist/index.js\n```\n\nThe generated manifest exposes the module through `imports.renderer`. CSS plugins are rejected and no framework-specific behavior is added.\n","readmeFilename":"README.md","_rev":"1-ab064e0c48675361fb92f97fbdea9ad2"}