@aglyn/aglyn 1.0.0-beta.143 → 1.0.0-beta.145

package/README.md

@@ -1,11 +1,122 @@
 # @aglyn/aglyn
 
-This library was generated with [Nx](https://nx.dev).
+The core of Aglyn: the platform's data model (hosts, screens, layouts, node
+trees), the runtime managers that hold components, plugins and the canvas, and
+the framework-independent utilities the rest of the `@aglyn` packages are built
+on. Install it if you are building on Aglyn's model: a renderer, an editor, a
+plugin, or a tool that reads and writes Aglyn documents.
 
-## Building
+> Beta. Published from the Aglyn monorepo under the `beta` dist-tag; APIs can change between beta releases.
 
-Run `nx build aglyn` to build the library.
+## Install
 
-## Running unit tests
+    npm install @aglyn/aglyn@beta
 
-Run `nx test aglyn` to execute the unit tests via [Jest](https://jestjs.io).
+Peer dependencies:
+
+- `react` is required.
+- `next`, `firebase`, `@mui/material` and `@mui/system` are declared optional
+  (`peerDependenciesMeta`). The package installs and bundles with only `react`.
+  Bring the optional ones only for the modules that use them:
+  - `@mui/material` for the consent UI modules
+    (`@aglyn/aglyn/app-utils/consent-banner-ui`,
+    `@aglyn/aglyn/app-utils/consent-preferences-dialog`); `@mui/material` and
+    `@mui/system` also supply types that some node and component type
+    definitions refer to.
+  - `next` for `@aglyn/aglyn/app-utils/advertising-tag-mounts`, which uses
+    `next/script`.
+  - `firebase` is declared for apps that pair the model with Firebase, as
+    Aglyn's own apps do. No module in this package needs it to load.
+
+This is the "logic only" consumer story: `@aglyn/aglyn` together with
+`@aglyn/besigner` installs with `react` as the only peer, and needs no UI
+library, no `next`, and no Firebase SDK.
+
+## What's in it
+
+Entry points:
+
+- `@aglyn/aglyn` is the full barrel, for client code.
+- `@aglyn/aglyn/server` is the server-safe barrel. It re-exports the same
+  model, managers and pure utilities without the client React contexts, so it
+  can be imported from React Server Components. It also carries the modules
+  that use Node built-ins or a JavaScript parser and are therefore kept out of
+  the client barrel: the Web-to-`(req, res)` API adapter, API idempotency,
+  the person key, the plugin bundle checks, and the server side of realm
+  plugins.
+- `@aglyn/aglyn/*` maps to a file under `src/lib`, for example
+  `@aglyn/aglyn/aglyn` or `@aglyn/aglyn/app-utils/markdown-lite`. A subpath
+  names a file, not a folder. Importing by subpath keeps a bundle to what it
+  uses.
+
+Main areas under `src/lib`:
+
+- `aglyn` is the runtime singleton. It exports `aglyn` and its parts:
+  `emitter`, `plugins`, `components`, `canvas` and `logger`. The instance is
+  keyed on `globalThis`, so duplicate module copies in one JavaScript realm
+  share one runtime.
+- `types` holds the node and screen model: `NodeSchema`, `NodesMap`,
+  `ComponentSchema`, `PresetSchema`, `ScreenSchema`, routing and AST types.
+- `foundation` holds the platform document types (`AglynHost`, `AglynScreen`,
+  `AglynLayout`, `AglynHostTheme`, organization and billing shapes, and their
+  id types) and shared constants.
+- `emit-manager` is `EmitManager` (an `eventemitter2` emitter) and the
+  `AglynEvent` enum of lifecycle and action events.
+- `components-manager` is `ComponentManager`, the registry of component
+  factories, their schemas, and presets.
+- `plugin-manager` is `PluginManager` (plugin registration and dependency
+  status) plus the plugin seams: the plugin loader (`createPluginLoader`),
+  contributions, configuration, permissions, entitlements, events, services
+  and jobs. Aglyn's feature plugins attach to the platform through these.
+- `canvas-manager` is `CanvasManager`, the observable node tree: set, create,
+  delete, duplicate, reparent and reorder nodes, with undo and redo history.
+- `app-utils` is a large set of pure helpers over the model: node composition
+  and sanitizing, binding tokens and variables, datasets and collections, SEO
+  and sitemap helpers, the markdown-lite dialect, permissions and roles,
+  consent, analytics keys, media references, and more. Its React contexts
+  (site context, media picker, enabled plugins and others) are exported from
+  the client barrel only.
+- `utils` has the feature-flag predicates such as `isFeatureEnabled`.
+
+## Usage
+
+```ts
+import { AglynEvent, canvas, components, emitter } from '@aglyn/aglyn'
+
+emitter.on(AglynEvent.COMPONENT_REGISTERED, ({ $id }) => {
+  console.log('registered', $id)
+})
+
+components.registerComponent(MyBox, {
+  $id: 'my-box',
+  pluginId: 'my-plugin',
+  displayName: 'My box',
+})
+
+components.getSchema('my-box')
+
+// `nodes` is a NodesMap: node id -> NodeSchema
+canvas.setNodes(nodes)
+const root = canvas.rootNode
+```
+
+From a Server Component or other server code:
+
+```ts
+import type { AglynScreen, NodeSchema } from '@aglyn/aglyn/server'
+```
+
+## How it fits
+
+`@aglyn/aglyn` is the `core` scope of the package map. It imports only itself
+and the generic `@aglyn/shared-*` packages. It holds no rendering, no designer,
+no tenancy and no plugin: the core never imports a plugin, and a plugin's
+domain lives in that plugin. Everything else stands on it:
+`@aglyn/aglyn-node-renderer` turns its node trees into React,
+`@aglyn/besigner` and `@aglyn/besigner-ui` edit them, the `@aglyn/tenant-*`
+packages serve them, and every `@aglyn/plugins-*` package registers into its
+managers.
+
+## License
+
+Apache-2.0. Source: https://github.com/aglyn/aglyn/tree/main/libs/aglyn

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aglyn/aglyn",
-  "version": "1.0.0-beta.143",
+  "version": "1.0.0-beta.145",
   "license": "Apache-2.0",
   "homepage": "https://aglyn.com",
   "repository": {
@@ -22,6 +22,10 @@
       "types": "./src/server.d.ts",
       "default": "./src/server.js"
     },
+    "./foundation": {
+      "types": "./src/lib/foundation/index.d.ts",
+      "default": "./src/lib/foundation/index.js"
+    },
     "./*": {
       "types": "./src/lib/*.d.ts",
       "default": "./src/lib/*.js"
@@ -29,15 +33,15 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@aglyn/shared-data-enums": "1.0.0-beta.143",
-    "@aglyn/shared-data-mdi": "1.0.0-beta.143",
-    "@aglyn/shared-data-types": "1.0.0-beta.143",
-    "@aglyn/shared-util-email": "1.0.0-beta.143",
-    "@aglyn/shared-util-http": "1.0.0-beta.143",
-    "@aglyn/shared-util-logger": "1.0.0-beta.143",
-    "@aglyn/shared-util-timestamp": "1.0.0-beta.143",
-    "@aglyn/shared-util-tools": "1.0.0-beta.143",
-    "@aglyn/shared-util-vendor": "1.0.0-beta.143",
+    "@aglyn/shared-data-enums": "1.0.0-beta.145",
+    "@aglyn/shared-data-mdi": "1.0.0-beta.145",
+    "@aglyn/shared-data-types": "1.0.0-beta.145",
+    "@aglyn/shared-util-email": "1.0.0-beta.145",
+    "@aglyn/shared-util-http": "1.0.0-beta.145",
+    "@aglyn/shared-util-logger": "1.0.0-beta.145",
+    "@aglyn/shared-util-timestamp": "1.0.0-beta.145",
+    "@aglyn/shared-util-tools": "1.0.0-beta.145",
+    "@aglyn/shared-util-vendor": "1.0.0-beta.145",
     "@data-driven-forms/react-form-renderer": "^4.2.0",
     "@msgpack/msgpack": "^3.1.3",
     "@types/unist": "^3.0.3",
@@ -56,6 +60,20 @@
     "next": "16.3.3",
     "react": "^19.2.8"
   },
+  "peerDependenciesMeta": {
+    "@mui/material": {
+      "optional": true
+    },
+    "@mui/system": {
+      "optional": true
+    },
+    "firebase": {
+      "optional": true
+    },
+    "next": {
+      "optional": true
+    }
+  },
   "sideEffects": [
     "./src/lib/foundation/constants/_internal.*",
     "./src/lib/foundation/constants/symbol.*"

package/src/lib/app-utils/entry-preview-link.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * The two names the live-site preview of a collection entry is built from
+ * (AGL-3205), and nothing else.
+ *
+ * DEPENDENCY-FREE ON PURPOSE. The tenant middleware reads the parameter name
+ * to decide whether a request is a preview, and the middleware runs on the
+ * edge: it deep-imports its pure helpers precisely so a bundle meant to answer
+ * in a millisecond does not drag a barrel — `accept-negotiation` and the theme
+ * utilities carry the same note. This module imports nothing at all, so it
+ * costs the edge bundle two string constants.
+ *
+ * Four surfaces have to agree on these, in three different apps: the console
+ * mints the URL, the tenant middleware routes on the parameter, the tenant
+ * preview page reads it, and the screens authoring rules reserve the segment.
+ * A literal in four places is a rename waiting to break one of them.
+ */
+/**
+ * The query parameter a preview link carries.
+ *
+ * Namespaced with the brand so it cannot collide with a parameter a customer's
+ * own page already reads, and `snake_case` to match the `aglyn_edit_hint`
+ * cookie rather than the `data-aglyn-*` attribute family.
+ */
+export declare const ENTRY_PREVIEW_PARAM = "aglyn_preview";
+/**
+ * The internal path segment the middleware rewrites a preview request to —
+ * `/{host}/{scheme}/aglyn-preview/{the public path}`.
+ *
+ * Never seen by a reader: the address bar keeps the post's real URL. It exists
+ * because the preview MUST be a different Next route from the catch-all, which
+ * is ISR-cached per pathname and would otherwise serve an unpublished post to
+ * the public for an hour.
+ *
+ * It is a reserved screen slug for the ordinary reason a segment ends up in
+ * {@link RESERVED_SCREEN_ROUTE_SEGMENTS}: a static route folder wins over the
+ * optional catch-all beside it, so a screen published at `/aglyn-preview/…`
+ * would be answered by the preview route and never render. Brand-prefixed so
+ * the slug it costs a customer is one nobody wants.
+ */
+export declare const ENTRY_PREVIEW_ROUTE_SEGMENT = "aglyn-preview";

package/src/lib/app-utils/entry-preview-link.js

@@ -0,0 +1,54 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * The two names the live-site preview of a collection entry is built from
+ * (AGL-3205), and nothing else.
+ *
+ * DEPENDENCY-FREE ON PURPOSE. The tenant middleware reads the parameter name
+ * to decide whether a request is a preview, and the middleware runs on the
+ * edge: it deep-imports its pure helpers precisely so a bundle meant to answer
+ * in a millisecond does not drag a barrel — `accept-negotiation` and the theme
+ * utilities carry the same note. This module imports nothing at all, so it
+ * costs the edge bundle two string constants.
+ *
+ * Four surfaces have to agree on these, in three different apps: the console
+ * mints the URL, the tenant middleware routes on the parameter, the tenant
+ * preview page reads it, and the screens authoring rules reserve the segment.
+ * A literal in four places is a rename waiting to break one of them.
+ */ /**
+ * The query parameter a preview link carries.
+ *
+ * Namespaced with the brand so it cannot collide with a parameter a customer's
+ * own page already reads, and `snake_case` to match the `aglyn_edit_hint`
+ * cookie rather than the `data-aglyn-*` attribute family.
+ */ export const ENTRY_PREVIEW_PARAM = 'aglyn_preview';
+/**
+ * The internal path segment the middleware rewrites a preview request to —
+ * `/{host}/{scheme}/aglyn-preview/{the public path}`.
+ *
+ * Never seen by a reader: the address bar keeps the post's real URL. It exists
+ * because the preview MUST be a different Next route from the catch-all, which
+ * is ISR-cached per pathname and would otherwise serve an unpublished post to
+ * the public for an hour.
+ *
+ * It is a reserved screen slug for the ordinary reason a segment ends up in
+ * {@link RESERVED_SCREEN_ROUTE_SEGMENTS}: a static route folder wins over the
+ * optional catch-all beside it, so a screen published at `/aglyn-preview/…`
+ * would be answered by the preview route and never render. Brand-prefixed so
+ * the slug it costs a customer is one nobody wants.
+ */ export const ENTRY_PREVIEW_ROUTE_SEGMENT = 'aglyn-preview';
+
+//# sourceMappingURL=entry-preview-link.js.map

package/src/lib/app-utils/entry-preview-link.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/entry-preview-link.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * The two names the live-site preview of a collection entry is built from\n * (AGL-3205), and nothing else.\n *\n * DEPENDENCY-FREE ON PURPOSE. The tenant middleware reads the parameter name\n * to decide whether a request is a preview, and the middleware runs on the\n * edge: it deep-imports its pure helpers precisely so a bundle meant to answer\n * in a millisecond does not drag a barrel — `accept-negotiation` and the theme\n * utilities carry the same note. This module imports nothing at all, so it\n * costs the edge bundle two string constants.\n *\n * Four surfaces have to agree on these, in three different apps: the console\n * mints the URL, the tenant middleware routes on the parameter, the tenant\n * preview page reads it, and the screens authoring rules reserve the segment.\n * A literal in four places is a rename waiting to break one of them.\n */\n\n/**\n * The query parameter a preview link carries.\n *\n * Namespaced with the brand so it cannot collide with a parameter a customer's\n * own page already reads, and `snake_case` to match the `aglyn_edit_hint`\n * cookie rather than the `data-aglyn-*` attribute family.\n */\nexport const ENTRY_PREVIEW_PARAM = 'aglyn_preview'\n\n/**\n * The internal path segment the middleware rewrites a preview request to —\n * `/{host}/{scheme}/aglyn-preview/{the public path}`.\n *\n * Never seen by a reader: the address bar keeps the post's real URL. It exists\n * because the preview MUST be a different Next route from the catch-all, which\n * is ISR-cached per pathname and would otherwise serve an unpublished post to\n * the public for an hour.\n *\n * It is a reserved screen slug for the ordinary reason a segment ends up in\n * {@link RESERVED_SCREEN_ROUTE_SEGMENTS}: a static route folder wins over the\n * optional catch-all beside it, so a screen published at `/aglyn-preview/…`\n * would be answered by the preview route and never render. Brand-prefixed so\n * the slug it costs a customer is one nobody wants.\n */\nexport const ENTRY_PREVIEW_ROUTE_SEGMENT = 'aglyn-preview'\n"],"names":["ENTRY_PREVIEW_PARAM","ENTRY_PREVIEW_ROUTE_SEGMENT"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;CAeC,GAED;;;;;;CAMC,GACD,OAAO,MAAMA,sBAAsB,gBAAe;AAElD;;;;;;;;;;;;;;CAcC,GACD,OAAO,MAAMC,8BAA8B,gBAAe"}

package/src/lib/app-utils/plan-entitlements.js

@@ -444,9 +444,28 @@ export const PLAN_ENTITLEMENTS = {
         // rule — a positive band with no rate beside it is usage past a bound
         // that is silently free, which `plan-entitlements.spec.ts` forbids.
         //
-        // `features.aiAssist` stays false: the band is credits, not the guided
-        // rung of the console assistant, exactly as on Free. The AI add-on adds
-        // `AI_ADDON_CREDITS_PER_MONTH.starter` on top and switches both flags on.
+        // `features.aiAssist` is TRUE, and AGL-3203 shipping it false was the
+        // defect AGL-3207 closes. The reasoning then was "the band is credits,
+        // not the guided rung, exactly as on Free" — but on Free the band IS
+        // spendable, through `aiGenerative`, which is the door the taste exists
+        // for. Starter carried neither flag, so it was the only row on the
+        // ladder sold a band with nothing to spend it through: 750 credits
+        // reachable only by buying the $9 add-on that was also the only thing
+        // that made them usable. "No plan bands at zero any more" was true of
+        // the number and false of the capability.
+        //
+        // It opens `aiAssist` rather than `aiGenerative` because that is the
+        // shape of every paid rung above it — the included band funds the guided
+        // assistant and generation is the add-on. Opening the generative door
+        // here instead would hand the FIRST paid rung a door Pro through Agency
+        // have to buy.
+        //
+        // No cost moves: `tier-margin-floor.spec.ts` already prices this tier's
+        // assist term at 100% burn of the 750 credits, 75¢/mo. A door does not
+        // widen a band; it only makes spend that was already modeled reachable.
+        //
+        // The AI add-on adds `AI_ADDON_CREDITS_PER_MONTH.starter` on top and
+        // switches `aiGenerative` on as well.
         assistCreditsPerMonth: 750,
         apiRequestsPerMonth: 0,
         datasetsPerOrg: 3,
@@ -481,7 +500,7 @@ export const PLAN_ENTITLEMENTS = {
             removeBranding: true,
             scheduledPublishing: false,
             marketplaceSelling: false,
-            aiAssist: false,
+            aiAssist: true,
             aiGenerative: false,
             workflows: true,
             dataStore: true,