pict-microapp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Steven Velozo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,180 @@
+# pict-microapp
+
+Present a large pict application as a small, focused one.
+
+A **micro app** is not a fork and not a rebuild: it is the *same* application, booted the same way,
+with a smaller surface. You keep every view, provider, template, style and bug fix the host app
+already has — and an enhancement to the host lands in every micro app on its next build — but the
+routes, the navigation and the landing page are the micro app's own.
+
+```js
+const libHostApplication = require('../../some-big-app/source/Big-Application-Web.js');
+const libMicroApp = require('pict-microapp');
+
+class WidgetInspection extends libMicroApp.composeMicroApp(libHostApplication, require('./Widget-MicroApp-Manifest.js'),
+	{
+		HostRouterProviderHash: 'BigApplicationRouter',
+		NavigationGateMethod: '_applyCustomerNavGate',
+		HostPermittedMethod: '_navItemPermitted',
+		IsPrivilegedMethod: '_isSuperUser'
+	}) {}
+
+module.exports = WidgetInspection;
+module.exports.default_configuration = libHostApplication.default_configuration;
+```
+
+## The seam
+
+A pict application registers every route it owns through one funnel: `PictRouter.addRoute`. That is
+true of the application's own routes, of routes contributed by modules like `pict-section-workspace`,
+and of the wildcard record-set routes from `pict-section-recordset`.
+
+`pict-microapp` wraps that funnel with an allow list. The host's registration code runs completely
+unmodified — it just finds that some of what it registered did not stick. Nothing else about the
+boot sequence changes, which is what keeps a micro app cheap to build and cheap to keep working as
+the host evolves.
+
+Three seams, in order of how much they matter:
+
+| Seam | What it does |
+| --- | --- |
+| `gateRouter()` | Wraps `addRoute` with the manifest's allow / deny / guard decision |
+| `applyNavigationGraph()` / `applyNavigationGate()` | Swaps the navigation graph and its visibility filter |
+| `applyDefaultRoute()` | Re-points the landing route |
+
+## What this does not do
+
+**It does not make the JavaScript bundle smaller.** The host's module graph is still bundled whole,
+because the micro app extends the host's application class and that class requires everything. A
+micro app slims the app the *user* sees, not the bytes the browser downloads.
+
+That is usually the right trade. The alternative — composing an app out of deep subpath requires
+into the host — genuinely shrinks the bundle, but it means reimplementing the host's boot sequence
+and re-deciding it every time the host changes, which is exactly the coupling a micro app is trying
+to avoid. Reach for it when download size becomes a real constraint, not before.
+
+## The manifest
+
+Everything a micro app declares lives in one plain object.
+
+```js
+module.exports =
+{
+	Name: 'Widget Inspection',
+	Hash: 'WidgetInspection',
+
+	// Where the app lands, and where a blocked route bounces to.
+	DefaultRoute: '/WidgetDashboard',
+
+	Routes:
+	{
+		// Route patterns exactly as the host registers them. A trailing '*' is a prefix glob.
+		// An EMPTY list exposes everything — useful when you only want different navigation.
+		Allow:
+			[
+				'/WidgetDashboard',
+				'/WidgetDashboard/:View',
+				'/Widget/Workspace/:ID',
+				'/Widget/Workspace/:ID/:Tab',
+				'/Gadget/*'
+			],
+
+		// Removed even when Allow would admit them. Deny wins.
+		Deny: [],
+
+		// Wildcard record-set routes ('/PSRS/:RecordSet/List') are registered ONCE by the host and
+		// fan out over every entity it knows, so they cannot be refused per-entity at registration
+		// time. They are GUARDED instead: the route registers, but its handler bounces to Fallback
+		// when the resolved entity is not listed here. An empty list exposes every entity.
+		EntityParameter: 'RecordSet',
+		Entities: [ 'Widget', 'Gadget' ],
+
+		// A hash matching no surviving route lands on Fallback rather than on a blank page.
+		CatchUnmatched: true,
+		Fallback: '',
+
+		// Always admitted, whatever Allow says — the boot and logout plumbing.
+		AlwaysAllow: [ '/', '/Logout' ]
+	},
+
+	Navigation:
+	{
+		// The graph this micro app renders, in the host navigation module's own shape.
+		Sections: [ /* … */ ],
+
+		// Keep the host's capability / module / session gates …
+		HonorHostGates: true,
+		// … but drop its audience short-circuit. See below.
+		SuperUserSeesEverything: true
+	},
+
+	Branding: { Title: 'Widget Inspection' }
+};
+```
+
+### Why `SuperUserSeesEverything` defaults to true
+
+A host that serves many audiences usually trims its own large graph hard. The platform application
+this module was extracted from, for example, shows platform super-users *only* the handful of
+cross-customer destinations, because the full menu is meaningless without a customer context.
+
+Applied to a micro app graph — which is *already* the slimmed surface — that trim empties the menu
+completely, for exactly the staff building and demoing the app. So the default keeps the host's real
+gates (session, module, capability) and drops only the audience short-circuit. A privileged session
+holds no entitlements in a customer's own tenancy, so it skips the capability test too; otherwise
+the menu blanks a second way the moment the capability map finishes loading.
+
+## Compose options
+
+`composeMicroApp(pHostApplicationClass, pManifest, pComposeOptions)` binds the manifest to one host's
+naming. Every option is a service hash or a method name on the host.
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `ProviderHash` | `'MicroApp'` | Where the provider registers on the host's pict instance |
+| `RouterProviderHash` | `'PictRouter'` | The `pict-router` provider — the route funnel |
+| `NavigationProviderHash` | `'Pict-Navigation'` | The `pict-section-navigation` provider |
+| `HostRouterProviderHash` | `RouterProviderHash` | The provider that owns `defaultRoute` (often an application router wrapping `pict-router`) |
+| `AttachOn` | `'onAfterInitializeAsync'` | The lifecycle hook the gate installs from |
+| `NavigationGateMethod` | `''` | Host method that installs the nav filter; overridden when named |
+| `HostPermittedMethod` | `''` | Host method answering "may this session see this item?" |
+| `IsPrivilegedMethod` | `''` | Host method answering "is this a privileged platform session?" |
+
+### Getting `AttachOn` right
+
+The gate must be installed **after the router provider exists** and **before the host registers its
+routes**. In a typical pict application the router provider is created during `onInitializeAsync`
+and routes are registered during the login / data-load cycle, which makes `onAfterInitializeAsync`
+the correct hook — the composed override runs the gate, then calls the host's implementation.
+
+If routes come up ungated, the hook fired too late. `MicroApp.routeTally` tells you immediately:
+
+```js
+_Pict.providers.MicroApp.routeTally;
+// { Name: 'Widget Inspection', Allowed: 24, Guarded: 7, Blocked: 96 }
+_Pict.providers.MicroApp.blockedRoutes;   // every pattern that did not survive
+```
+
+`blockedRoutes` is the first place to look when a screen is missing: a route you expected to keep
+but spelled differently than the host registers it shows up there.
+
+## Sharing the host's DOM shell
+
+Reused views render into the *host's* container addresses, which are baked into each view's
+configuration. A micro app's `index.html` therefore has to reproduce the host's DOM contract —
+the application container id, the loading-splash element, the dynamic-CSS `<style>` tag, and any
+wrapper class the host's layout modes toggle. Only the chrome *around* that contract (the top bar,
+the branding, the panels) is the micro app's to redesign.
+
+This is the one place a micro app is genuinely coupled to its host. Keep the host's ids; change the
+chrome.
+
+## Installation
+
+```bash
+npm install pict-microapp
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,59 @@
+{
+    "name": "pict-microapp",
+    "version": "1.0.0",
+    "description": "Present a large pict application as a small, focused one: a declarative manifest gates the host's routes, swaps its navigation graph and re-points its landing page, so a micro app reuses every view, provider and style the host already has.",
+    "main": "source/Pict-MicroApp.js",
+    "scripts": {
+        "test": "npx quack test",
+        "tests": "npx quack test -g",
+        "start": "node source/Pict-MicroApp.js",
+        "coverage": "npx quack coverage",
+        "build": "quack build",
+        "types": "tsc -p ."
+    },
+    "types": "types/Pict-MicroApp.d.ts",
+    "files": [
+        "source",
+        "types"
+    ],
+    "directories": {
+        "test": "test"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/fable-retold/pict-microapp.git"
+    },
+    "author": "steven velozo <steven@velozo.com>",
+    "license": "MIT",
+    "bugs": {
+        "url": "https://github.com/fable-retold/pict-microapp/issues"
+    },
+    "homepage": "https://github.com/fable-retold/pict-microapp#readme",
+    "devDependencies": {
+        "browser-env": "^3.3.0",
+        "chai": "^4.3.10",
+        "pict": "^1.0.372",
+        "pict-application": "^1.0.34",
+        "pict-router": "^1.0.10",
+        "quackage": "^1.3.0",
+        "typescript": "^5.9.3"
+    },
+    "mocha": {
+        "diff": true,
+        "extension": [
+            "js"
+        ],
+        "package": "./package.json",
+        "reporter": "spec",
+        "slow": "75",
+        "timeout": "5000",
+        "ui": "tdd",
+        "watch-files": [
+            "source/**/*.js",
+            "test/**/*.js"
+        ]
+    },
+    "dependencies": {
+        "pict-provider": "^1.0.13"
+    }
+}

package/source/Pict-MicroApp-Compose.js

@@ -0,0 +1,149 @@
+/**
+ * Pict MicroApp — compose a micro app class from a host application class and a manifest.
+ *
+ * This is the one-liner an app author writes:
+ *
+ *     const libHostApplication = require('some-big-pict-application');
+ *     const libMicroApp = require('pict-microapp');
+ *
+ *     class MyApp extends libMicroApp.composeMicroApp(libHostApplication, require('./MyApp-Manifest.js'), {...}) {}
+ *     module.exports = MyApp;
+ *     module.exports.default_configuration = libHostApplication.default_configuration;
+ *
+ * The composed class inherits everything the host does and overrides exactly four things: it
+ * registers the MicroApp provider, installs the route gate before the host registers routes,
+ * swaps the navigation graph and its visibility gate, and re-points the landing route.
+ *
+ * @author steven velozo <steven@velozo.com>
+ */
+
+const _DEFAULT_COMPOSE_OPTIONS =
+{
+	// Service hash the MicroApp provider is registered under on the host pict instance.
+	ProviderHash: 'MicroApp',
+
+	// Service hash of the pict-router provider (the route funnel the gate wraps).
+	RouterProviderHash: 'PictRouter',
+
+	// Service hash of the pict-section-navigation provider, when the host has one.
+	NavigationProviderHash: 'Pict-Navigation',
+
+	// Service hash of the provider that owns the host's `defaultRoute` property. Many hosts wrap
+	// pict-router in an application router provider; that wrapper is what holds the landing route.
+	// Defaults to RouterProviderHash when not set.
+	HostRouterProviderHash: '',
+
+	// The host lifecycle method the gate is installed from. The gate runs BEFORE the host's own
+	// implementation, so this must be a hook that fires after the router provider exists and
+	// before the host registers its routes.
+	AttachOn: 'onAfterInitializeAsync',
+
+	// Host method that installs the navigation visibility filter. Overridden so the micro app's
+	// gate wins. Set to '' to leave the host's navigation gate alone.
+	NavigationGateMethod: '',
+
+	// Host method that answers "may this session see this nav item?" — reused verbatim so
+	// capability and module gating keeps working against the micro app's own graph.
+	HostPermittedMethod: '',
+
+	// Host method that answers "is this a privileged platform session?" — used to keep the micro
+	// app's menu visible to platform staff who hold no tenant entitlements.
+	IsPrivilegedMethod: ''
+};
+
+/**
+ * Build a micro app application class from a host application class and a manifest.
+ *
+ * @param {Function} pHostApplicationClass - the host pict application class to present a subset of
+ * @param {Object} pManifest - the micro app manifest (see Pict-MicroApp-Manifest.js)
+ * @param {Object} [pComposeOptions] - the host binding options above
+ * @return {Function} a class extending the host application class
+ */
+function composeMicroApp(pHostApplicationClass, pManifest, pComposeOptions)
+{
+	if (typeof pHostApplicationClass !== 'function')
+	{
+		throw new Error('pict-microapp: composeMicroApp requires a host application class.');
+	}
+
+	const libPictMicroApp = require('./Pict-MicroApp.js');
+	const tmpOptions = Object.assign({}, _DEFAULT_COMPOSE_OPTIONS, pComposeOptions || {});
+	const tmpHostRouterProviderHash = tmpOptions.HostRouterProviderHash || tmpOptions.RouterProviderHash;
+	const tmpAttachOn = tmpOptions.AttachOn;
+	// The host class is only known at runtime, so it is cast to a constructor signature for the
+	// benefit of the declaration build; the composed class is deliberately untyped beyond that.
+	const tmpHostClass = /** @type {new (...pArguments: Array<any>) => any} */ (pHostApplicationClass);
+
+	class PictMicroApplication extends tmpHostClass
+	{
+		constructor(pFable, pApplicationOptions, pServiceHash)
+		{
+			super(pFable, pApplicationOptions, pServiceHash);
+
+			/** @type {any} */
+			this.pict;
+
+			// The host has finished registering its views and providers by now, so the navigation
+			// provider exists and the graph can be swapped in place.
+			this.pict.addProvider(tmpOptions.ProviderHash,
+				{
+					Manifest: pManifest,
+					RouterProviderHash: tmpOptions.RouterProviderHash,
+					NavigationProviderHash: tmpOptions.NavigationProviderHash
+				}, libPictMicroApp);
+
+			this.MicroApp.applyNavigationGraph();
+			this.MicroApp.applyBranding();
+		}
+
+		/**
+		 * The MicroApp provider for this application.
+		 *
+		 * @return {Object} the provider
+		 */
+		get MicroApp()
+		{
+			return this.pict.providers[tmpOptions.ProviderHash];
+		}
+	}
+
+	// The gate has to be installed from a lifecycle hook, and the hook's name is configuration, so
+	// the override is assigned onto the prototype rather than written in the class body.
+	PictMicroApplication.prototype[tmpAttachOn] = async function (fCallback)
+	{
+		const tmpMicroApp = this.MicroApp;
+		if (tmpMicroApp)
+		{
+			tmpMicroApp.gateRouter();
+			tmpMicroApp.installNotFound();
+			tmpMicroApp.applyDefaultRoute(this.pict.providers[tmpHostRouterProviderHash]);
+		}
+		return pHostApplicationClass.prototype[tmpAttachOn].call(this, fCallback);
+	};
+
+	// The host's navigation gate is usually written for the host's own (much larger) audience mix.
+	// Replacing it keeps the micro app's menu from being trimmed to nothing.
+	if (tmpOptions.NavigationGateMethod)
+	{
+		PictMicroApplication.prototype[tmpOptions.NavigationGateMethod] = function ()
+		{
+			const tmpMicroApp = this.MicroApp;
+			if (!tmpMicroApp)
+			{
+				return pHostApplicationClass.prototype[tmpOptions.NavigationGateMethod].call(this);
+			}
+			const tmpHostPermitted = tmpOptions.HostPermittedMethod
+				? (pItem) => this[tmpOptions.HostPermittedMethod](pItem)
+				: null;
+			const tmpIsPrivileged = tmpOptions.IsPrivilegedMethod
+				? () => this[tmpOptions.IsPrivilegedMethod]()
+				: (() => false);
+			return tmpMicroApp.applyNavigationGate(tmpHostPermitted, { IsPrivileged: tmpIsPrivileged });
+		};
+	}
+
+	return PictMicroApplication;
+}
+
+module.exports = composeMicroApp;
+module.exports.default_compose_options = _DEFAULT_COMPOSE_OPTIONS;

package/source/Pict-MicroApp-Manifest.js

@@ -0,0 +1,249 @@
+/**
+ * Pict MicroApp — manifest normalization and route matching.
+ *
+ * A micro app is described by a plain-object manifest: the routes it exposes, the navigation it
+ * renders, where it lands, and how it is branded. Everything in this file is pure — no pict, no
+ * DOM — so the matching rules can be unit tested headlessly.
+ *
+ * @author steven velozo <steven@velozo.com>
+ */
+
+/**
+ * The shape a normalized manifest always has, whatever the author wrote.
+ */
+const _DEFAULT_MANIFEST =
+{
+	// Display name of the micro app (used in logs and as the fallback document title).
+	Name: 'MicroApp',
+	// Stable identifier for this micro app.
+	Hash: 'MicroApp',
+
+	// The route the app lands on when it boots with no deep link, and where blocked routes bounce to.
+	// Written without the leading '#'.
+	DefaultRoute: '/',
+
+	Routes:
+	{
+		// Route patterns this micro app exposes, exactly as the host registers them (leading '#'
+		// optional). A trailing '*' makes an entry a prefix glob: '/Asset/*' allows every route
+		// whose pattern starts with '/Asset/'.
+		Allow: [],
+		// Patterns removed even when Allow would admit them. Deny wins.
+		Deny: [],
+		// Parameterized host routes that fan out over an entity name — the pict-section-recordset
+		// wildcards ('/PSRS/:RecordSet/List') are the motivating case. These cannot be dropped
+		// per-entity at registration time, so they are GUARDED instead: the route registers, but
+		// its handler bounces to the fallback route when the resolved entity is not in Entities.
+		EntityParameter: 'RecordSet',
+		Entities: [],
+		// When true (the default) an EntityParameter route is admitted and guarded. When false it
+		// is treated like any other route and must be listed in Allow to survive.
+		GuardEntityRoutes: true,
+		// Where a blocked entity bounces to. Defaults to DefaultRoute.
+		Fallback: '',
+		// When true, a hash that matches no surviving route lands on Fallback instead of nothing.
+		CatchUnmatched: true,
+		// Routes always admitted regardless of Allow — the boot, logout and default plumbing every
+		// host app needs to keep working.
+		AlwaysAllow: [ '/', '/Logout' ]
+	},
+
+	Navigation:
+	{
+		// The navigation graph this micro app renders, in the host navigation module's own shape.
+		// When empty the host's own graph is left alone.
+		Sections: [],
+		// Keep the host from replacing the graph later. Hosts rebuild their navigation as config and
+		// permissions resolve, which silently reverts the swap — usually after login, where it is
+		// easy to miss. Turn this off only if a micro app genuinely wants the host's later graph.
+		PinGraph: true,
+		// Drop the host's super-user short-circuit. A micro app's graph IS already the slimmed
+		// surface, so hiding all of it from platform staff is never what you want.
+		SuperUserSeesEverything: true,
+		// Keep the host's capability / module / session gates on top of the micro app graph.
+		HonorHostGates: true
+	},
+
+	Branding:
+	{
+		// document.title for the app.
+		Title: '',
+		// Title shown on the host's login screen, when the host supports one.
+		LoginTitle: ''
+	}
+};
+
+/**
+ * Strip a route to the canonical form used for comparison: no leading '#', exactly one leading '/',
+ * no trailing '/' (except the bare root).
+ *
+ * @param {String} pRoute - a route pattern or hash
+ * @return {String} the canonical route pattern
+ */
+function normalizeRoute(pRoute)
+{
+	let tmpRoute = String(pRoute == null ? '' : pRoute).trim();
+	if (tmpRoute.length < 1)
+	{
+		return '';
+	}
+	tmpRoute = tmpRoute.replace(/^#/, '');
+	tmpRoute = tmpRoute.replace(/^\/+/, '/');
+	if (tmpRoute.charAt(0) !== '/')
+	{
+		tmpRoute = `/${ tmpRoute }`;
+	}
+	// Collapse every trailing slash, not just the last one, so '//Widgets//' and '/Widgets' are the
+	// same route. The bare root keeps its slash.
+	tmpRoute = tmpRoute.replace(/\/+$/, '');
+	return (tmpRoute.length > 0) ? tmpRoute : '/';
+}
+
+/**
+ * Deep-ish merge of an author manifest over the defaults. Only the three known sub-objects are
+ * merged a level down; everything else is a straight overwrite.
+ *
+ * @param {Object} [pManifest] - the author's manifest
+ * @return {Object} a fully populated manifest
+ */
+function normalizeManifest(pManifest)
+{
+	const tmpManifest = (pManifest && (typeof pManifest === 'object')) ? pManifest : {};
+	const tmpNormalized = Object.assign({}, _DEFAULT_MANIFEST, tmpManifest);
+
+	tmpNormalized.Routes = Object.assign({}, _DEFAULT_MANIFEST.Routes, tmpManifest.Routes || {});
+	tmpNormalized.Navigation = Object.assign({}, _DEFAULT_MANIFEST.Navigation, tmpManifest.Navigation || {});
+	tmpNormalized.Branding = Object.assign({}, _DEFAULT_MANIFEST.Branding, tmpManifest.Branding || {});
+
+	tmpNormalized.DefaultRoute = normalizeRoute(tmpNormalized.DefaultRoute) || '/';
+	tmpNormalized.Routes.Allow = (tmpNormalized.Routes.Allow || []).map(normalizeRoute).filter((pEntry) => (pEntry.length > 0));
+	tmpNormalized.Routes.Deny = (tmpNormalized.Routes.Deny || []).map(normalizeRoute).filter((pEntry) => (pEntry.length > 0));
+	tmpNormalized.Routes.AlwaysAllow = (tmpNormalized.Routes.AlwaysAllow || []).map(normalizeRoute).filter((pEntry) => (pEntry.length > 0));
+	tmpNormalized.Routes.Fallback = normalizeRoute(tmpNormalized.Routes.Fallback) || tmpNormalized.DefaultRoute;
+	tmpNormalized.Routes.Entities = (tmpNormalized.Routes.Entities || []).map((pEntry) => String(pEntry));
+
+	return tmpNormalized;
+}
+
+/**
+ * Does a canonical route pattern match one allow/deny entry? An entry ending in '*' is a prefix
+ * glob; anything else is an exact pattern match (so '/Asset/Workspace/:ID' matches only the route
+ * registered with that exact parameter spelling).
+ *
+ * @param {String} pRoute - a canonical route pattern
+ * @param {String} pEntry - a canonical allow/deny entry
+ * @return {Boolean} whether the entry matches
+ */
+function routeMatchesEntry(pRoute, pEntry)
+{
+	if (pEntry === '*')
+	{
+		return true;
+	}
+	if (pEntry.charAt(pEntry.length - 1) === '*')
+	{
+		return (pRoute.indexOf(pEntry.slice(0, -1)) === 0);
+	}
+	return (pRoute === pEntry);
+}
+
+/**
+ * Does this route pattern fan out over the manifest's entity parameter (for example
+ * '/PSRS/:RecordSet/List' with an EntityParameter of 'RecordSet')?
+ *
+ * @param {String} pRoute - a canonical route pattern
+ * @param {String} pEntityParameter - the parameter name that names an entity
+ * @return {Boolean} whether the route is entity-parameterized
+ */
+function routeIsEntityParameterized(pRoute, pEntityParameter)
+{
+	if (!pEntityParameter)
+	{
+		return false;
+	}
+	return (pRoute.indexOf(`:${ pEntityParameter }`) > -1);
+}
+
+/**
+ * Decide what the gate should do with a route the host is trying to register.
+ *
+ * Returns one of three modes:
+ *   Allow — register it untouched.
+ *   Guard — register it, but wrap the handler so disallowed entities bounce to the fallback.
+ *   Block — do not register it at all.
+ *
+ * @param {Object} pManifest - a normalized manifest
+ * @param {String} pRoute - the route pattern the host passed to addRoute
+ * @return {{Mode: String, Route: String, Reason: String}} the decision
+ */
+function decideRoute(pManifest, pRoute)
+{
+	const tmpRoute = normalizeRoute(pRoute);
+	const tmpRoutes = pManifest.Routes;
+
+	if (tmpRoute.length < 1)
+	{
+		return { Mode: 'Block', Route: tmpRoute, Reason: 'EmptyRoute' };
+	}
+	for (const tmpEntry of tmpRoutes.Deny)
+	{
+		if (routeMatchesEntry(tmpRoute, tmpEntry))
+		{
+			return { Mode: 'Block', Route: tmpRoute, Reason: 'Denied' };
+		}
+	}
+	for (const tmpEntry of tmpRoutes.AlwaysAllow)
+	{
+		if (routeMatchesEntry(tmpRoute, tmpEntry))
+		{
+			return { Mode: 'Allow', Route: tmpRoute, Reason: 'AlwaysAllowed' };
+		}
+	}
+	// An empty Allow list means "expose everything" — a micro app that only wants a different
+	// navigation and landing page does not have to enumerate the host's whole route table.
+	if (tmpRoutes.Allow.length < 1)
+	{
+		return { Mode: 'Allow', Route: tmpRoute, Reason: 'NoAllowList' };
+	}
+	for (const tmpEntry of tmpRoutes.Allow)
+	{
+		if (routeMatchesEntry(tmpRoute, tmpEntry))
+		{
+			return { Mode: 'Allow', Route: tmpRoute, Reason: 'Allowed' };
+		}
+	}
+	if (tmpRoutes.GuardEntityRoutes && routeIsEntityParameterized(tmpRoute, tmpRoutes.EntityParameter))
+	{
+		return { Mode: 'Guard', Route: tmpRoute, Reason: 'EntityParameterized' };
+	}
+	return { Mode: 'Block', Route: tmpRoute, Reason: 'NotAllowed' };
+}
+
+/**
+ * Is an entity name exposed by this micro app? An empty Entities list means every entity is
+ * exposed (the manifest author did not want to constrain the record-set surface).
+ *
+ * @param {Object} pManifest - a normalized manifest
+ * @param {String} pEntity - the entity name resolved from the route
+ * @return {Boolean} whether the entity is exposed
+ */
+function entityPermitted(pManifest, pEntity)
+{
+	const tmpEntities = pManifest.Routes.Entities;
+	if (tmpEntities.length < 1)
+	{
+		return true;
+	}
+	return (tmpEntities.indexOf(String(pEntity)) > -1);
+}
+
+module.exports =
+{
+	default_manifest: _DEFAULT_MANIFEST,
+	normalizeManifest: normalizeManifest,
+	normalizeRoute: normalizeRoute,
+	routeMatchesEntry: routeMatchesEntry,
+	routeIsEntityParameterized: routeIsEntityParameterized,
+	decideRoute: decideRoute,
+	entityPermitted: entityPermitted
+};