@niscorp/nisc 0.2.2 → 0.2.4

package/AGENTS.md

@@ -2,6 +2,8 @@
 
 > **Reading this from `node_modules/@niscorp/nisc/`?** It is the rulebook for the nisc version installed beside it, shipped with it. Where it names a path in the nisc repository, look here instead: `packages/<name>/README.md` and `DESIGN.md` are `node_modules/@niscorp/<name>/`; `/STYLE_GUIDE.md` is beside this file; the lab apps it holds up as examples (`apps/lab/atrium`, `mythos`, …) and `docs/` are at [github.com/moccadroid/niscorp](https://github.com/moccadroid/niscorp). An app made by `npm create nisc` points its own `AGENTS.md` here.
 
+> **Changing nisc itself — a package, not an app built on it?** The `@niscorp` packages are live on npm and may be in use by third parties. No change may break an app that works today, and a breaking change is never yours to decide: it is a last resort that needs the maintainer's explicit approval *before* it is written. Read `/STYLE_GUIDE.md`, "The packages are live", first.
+
 For agents generating or reviewing a nisc application. This file states the application-level rules, and it presumes no app that came before it — but it is not the whole specification. The **grammars** live in the package docs, and they are required reading, not background: a layout node, an `ActionDefinition`, a Prism config, a charter document and a Vex DSL are each defined in their own package's `README.md` and `DESIGN.md`. Read the doc for a package before authoring that package's artifact. This file governs how they compose into an application.
 
 ## The thesis
@@ -79,6 +81,8 @@ Pick per need; every piece works standalone. Nova is the only mandatory one for
 3. Reusable chrome (dialog frame, panel, drawer) is a fragment composed when an action is loaded (`with: [...]`), not a wrapper component. Modality is arrangement — an action loaded onto an overlay canvas with fragment chrome — never a `$.modalOpen` flag inside an action.
 4. Shell state is the truth. Routing (D5), if wired, is a data table mapping paths ↔ actions, synced by an adapter; Nova stays URL-agnostic. A **page** is not routing inside the app: it is a separate manifest at a path (`pages`), drawn and let go, and a path's parameters seed the canvas the page names — nothing else about a URL reaches an action.
 
+4a. What a page says about itself is a node in a layout. Its title, its description and the card shown where a link to it is pasted are a `nova:head` node — props `title`, `description`, `image`, `kind`, `structured`, bound to the action's data like any other node's — which draws nothing and is written into the document's `<head>` by whoever draws the page (`nisc build`/`export`/`start`, moss's `renderDocument`); in the page the tab's title follows it. No hook builds a head, no script rewrites a drawn file, and `index.html` holds only what is the same on every page. Where a page lives is never in a layout: `site` in `nisc.config.ts` and the path say it. Whether it sits in the action's own layout or in chrome around it (a fragment, the frame) is arrangement, like everything else.
+
 **Data**
 
 5. All data in and out of an action flows through its declared `endpoints`. Shaping is declared on the endpoint: a static request body is plain JSON; a body derived from the action's data is a Prism config, kept in a sibling `.prism.ts`. Prefer plain JSON when no mapping is required. Components never shape data.

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # @niscorp/nisc
 
+## 0.2.4
+
+### Patch Changes
+
+- af903c6: A page's head is its screen's own. `nisc export` wrote every path with the built `index.html`'s `<head>`, so a site with more than one page shipped each of them under the front page's title, description, preview card and canonical address.
+
+  What a screen says about itself is now a node in a layout: nova's `nova:head`, with `title`, `description`, `image`, `kind` and `structured` bound to the action's data like any other node's props. It draws nothing — no adapter builds an element for it, no registry has to hold it, and a component is never handed one as a child — and it rides in the render tree, so it reaches a shell in the page, a snapshot a server drew and the trees on a wire alike. `headOf(api)` reads it off any of them; with more than one on the screen the last one speaks.
+  - **nova** — `HEAD_NAME`, `HeadPropsSchema`, `HEAD_META`, `headOf`, `isHeadNode`; and `@niscorp/nova/document`: `placeHead` writes a head into an HTML document (the tag that said the same thing is replaced, a missing one is added before `</head>`, everything else is left as it was; values are escaped) and `createTitleKeeper` keeps a tab's title on it. The DOM, React and Vue adapters keep the title on the head as the screen moves, and give the page's own back when the screen has none.
+  - **cli** — `build`, `export` and `start` write each path's document with its screen's head. "Same twice" also fails a boot that says a different head the second time, and the route table says whose head each path goes out with once an app has one. New config field `site`: the address the site is served at. With it every path says its own canonical address (`<link rel="canonical">`, `og:url`) and a head's picture gets a whole address; a build with several paths, a canonical tag in `index.html` and no `site` says so.
+  - **moss** — `renderDocument` and `exportDocuments` do the same from the snapshot (`site` on the config, `head` on the result), and the terminal keeps the tab's title off the wire for every render target.
+  - **create-nisc** — the two own-shell templates say their welcome screen's head.
+
+  **What to change:** nothing. An app with no `nova:head` node and no `site` is built, served and drawn exactly as before. An app that rewrote its exported files to give each page a head can delete that step: put the node in the layout and set `site`.
+
+- Updated dependencies [af903c6]
+  - @niscorp/nova@0.1.4
+  - @niscorp/moss@0.2.4
+  - @niscorp/cli@0.2.3
+
+## 0.2.3
+
+### Patch Changes
+
+- 80e1ee8: Documentation: the packages are live, and releases are compatible. `STYLE_GUIDE.md` gains "The packages are live" — a release does not break an app that works on the one before it; what should go is deprecated and stays; a breaking change is a last resort that needs the maintainer's approval before it is written — and `AGENTS.md` points every agent changing nisc itself to it. The status lines that said "pre-1.0, breaking changes expected" (nova), "API is pre-1.0 and moves" (moss) and "everything else may move" (tide) now say the same. moss's deprecated `installedIntegrations` is no longer described as scheduled for removal: it stays on the type. The style guide's Node floor is corrected to 22.12, what every package's `engines` already says. No code changes.
+- Updated dependencies [48da7db]
+- Updated dependencies [8a04243]
+- Updated dependencies [8a04243]
+- Updated dependencies [80e1ee8]
+  - @niscorp/moss@0.2.3
+  - @niscorp/cli@0.2.2
+  - @niscorp/nova@0.1.3
+  - @niscorp/tide@0.1.2
+
 ## 0.2.2
 
 ### Patch Changes

package/README.md

@@ -14,8 +14,12 @@ was released with, so installing `@niscorp/nisc@0.4.0` installs the set that
 was tested as nisc 0.4.0. Import from the packages themselves
 (`@niscorp/nova`, `@niscorp/moss`, …).
 
-Its version moves whenever any member's does, and it breaks whenever any member
-breaks — `pnpm check:changesets` refuses a release plan that forgets.
+Its version moves whenever any member's does. The packages are live, and a
+release is compatible with the one before it: installing a newer
+`@niscorp/nisc` does not break an app that worked on the older one. A breaking
+release is a last resort that needs the maintainer's approval; if one ever
+ships in a member, this package breaks with it — `pnpm check:changesets`
+refuses a plan that is missing either the approval or this.
 
 ## The rulebook
 

package/STYLE_GUIDE.md

@@ -4,6 +4,22 @@ Rules for writing code in this codebase. Short, focused on what matters.
 
 ---
 
+## The packages are live
+
+The `@niscorp` packages are published on npm, and people we have never met may be building on them. That decides what a change may do.
+
+- **A release does not break an app that works on the release before it.** If an app would have to change anything to keep working — an import, a call, a type it relied on, a config field, an artifact, a command or a flag — the change is breaking.
+- **A breaking change is a failure of the design, not a kind of release.** Find the compatible shape first: add beside what is there, keep the old spelling working, make new behaviour something an app opts into. What should go is marked `@deprecated` and stays. A default may get better; where some setup would stop working under the new one, it gets a way to keep the old, and the changeset names that setup.
+- **Nobody breaks a package on their own judgment.** If you believe a break cannot be avoided: stop before writing it. Say so first — at the top of what you report, not in a summary of work done — with the compatible shapes you tried and why each one fails, and wait. It ships only with the maintainer's explicit approval, as the last resort.
+- **Not sure whether it breaks?** That is the same stop: say what would change for an app that exists today, and ask.
+- **Data never breaks; it migrates.** Tables and stored documents move through strata sequences (AGENTS.md 17–20).
+
+Mechanically: every package change carries a changeset, and its bump is `patch`. Below 1.0 a `minor` is the breaking bump, and `pnpm check:changesets` refuses one whose changeset does not carry its approval (`docs/releasing.md`).
+
+This binds the packages. An app is its own to change.
+
+---
+
 ## TypeScript Strictness
 
 - `strict: true` in tsconfig. Always.
@@ -226,5 +242,5 @@ export const createShell = (config: ShellConfig, bus: MessageBus, reg: Registry,
 ## Build
 
 - ESM source, dual ESM/CJS output via tsup.
-- Target ES2022, Node >= 18.18.
+- Target ES2022, Node >= 22.12 (what every package's `engines` says).
 - Minimal dependencies. Every dep must earn its place.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@niscorp/nisc",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "The nisc platform as one known-compatible set: every @niscorp package, each pinned to the exact version it was released with.",
   "license": "Apache-2.0",
   "repository": {
@@ -20,15 +20,15 @@
   },
   "dependencies": {
     "@niscorp/charter": "0.1.1",
-    "@niscorp/cortex": "0.1.1",
-    "@niscorp/cli": "0.2.1",
+    "@niscorp/cli": "0.2.3",
     "@niscorp/loom": "0.1.1",
-    "@niscorp/moss": "0.2.2",
-    "@niscorp/nova": "0.1.2",
-    "@niscorp/prism": "0.1.2",
+    "@niscorp/cortex": "0.1.1",
+    "@niscorp/moss": "0.2.4",
+    "@niscorp/nova": "0.1.4",
     "@niscorp/signal": "0.1.1",
+    "@niscorp/prism": "0.1.2",
     "@niscorp/strata": "0.1.1",
-    "@niscorp/tide": "0.1.1",
+    "@niscorp/tide": "0.1.2",
     "@niscorp/vex": "0.1.1",
     "@niscorp/solid": "0.1.0"
   },