@bleedingdev/modern-js-create 3.5.0-ultramodern.9 → 3.5.0-ultramodern.90

package/dist/types/ultramodern-workspace/delivery-unit-schema/types.d.ts

@@ -0,0 +1,291 @@
+/**
+ * Canonical MicroVertical delivery contracts (W4).
+ *
+ * This module DEFINES the canonical shapes only. It is intentionally UNWIRED:
+ * no generator, normalizer, or runtime path imports it, and it does not change
+ * any emitted output. The v1 down-projection here is a pure, tested function;
+ * it is not invoked by any generation path.
+ *
+ * Binding vocabulary: root `CONTEXT.md`, ADR-0019 (Federated Loading, Unified
+ * Delivery), ADR-0020 (Zoned Surface Versioning). See `packages/toolkit/create/delivery-unit-schema-SPEC.md` for the
+ * SurfaceRef grammar, invariants, and the v1 mapping table.
+ *
+ * TS constraint: plain types + pure functions only. This file is scanned by
+ * `tsgo-boundary.test.ts`; it must never import TypeScript compiler APIs.
+ */
+import { type DeliveryUnitRecord } from '@modern-js/utils/universal';
+import type { JsonObject, Ownership, WorkspaceApp } from '../types';
+/**
+ * The single accountable owner of a delivery unit. Exactly one owner per unit
+ * (CONTEXT.md: "MicroVertical never [has more than] one owner").
+ */
+export type DeliveryUnitOwner = {
+    kind: 'team' | 'agent' | 'agent-team';
+    id: string;
+    contact?: string;
+};
+/**
+ * Exact platform-baseline pins resolved for this unit. Composition-time
+ * singletons only (CONTEXT.md: Platform Baseline). Verticals never pick their
+ * own version; the cohort is advanced platform-wide.
+ */
+export type BaselineCohortResolved = {
+    react: string;
+    tanstackRouter: string;
+    effect: string;
+    tailwind: string;
+};
+/**
+ * A baseline cohort is an opaque, stable id plus the exact record it resolves
+ * to. The id is the unit of comparison; the resolved record is the evidence.
+ */
+export type BaselineCohort = {
+    cohortId: string;
+    resolved: BaselineCohortResolved;
+};
+export type ExternalRetirement = {
+    /** SurfaceRef (canonical string) of the successor major, when known. */
+    supersededBy?: string;
+    /** Opaque retirement marker (window id / date string), owner-defined. */
+    sunsetAfter?: string;
+};
+/**
+ * External-publication terms. A breaking change ships as a new major exposed
+ * side by side with the previous major until known consumers migrate.
+ */
+export type ExternalPublication = {
+    surfaceMajor: number;
+    /** Opaque compatible-baseline descriptor (e.g. a cohort range id). */
+    baselineCompatibility: string;
+    retirement?: ExternalRetirement;
+};
+/**
+ * Zone discriminated union. `external` carries its terms atomically: it is a
+ * type error to be in the external zone without an {@link ExternalPublication}
+ * record. Default is `coordinated` (see {@link resolvePublicationZone}).
+ */
+export type PublicationZone = {
+    zone: 'coordinated';
+} | {
+    zone: 'external';
+    external: ExternalPublication;
+};
+export type SurfaceLocationPlatform = 'browser-mf' | 'node-mf' | 'http' | 'cloudflare-binding';
+/**
+ * A concrete per-platform location for a surface. Discriminated on `platform`
+ * so each platform carries only the address shape it can actually resolve.
+ * (ADR-0019 §3: UI/API/backend addresses are derived, platform-appropriate.)
+ */
+export type SurfaceLocation = {
+    platform: 'browser-mf';
+    manifestUrl: string;
+} | {
+    platform: 'node-mf';
+    manifestUrl: string;
+} | {
+    platform: 'http';
+    address: string;
+} | {
+    platform: 'cloudflare-binding';
+    serviceBinding: string;
+};
+export type SurfaceKind = 'component' | 'route' | 'api' | 'backend';
+export type ApiProtocol = 'rest' | 'rpc' | 'graphql';
+type SurfaceCommon = {
+    surfaceId: string;
+    /** Per-platform locations. Never mixed across delivery-unit build markers. */
+    locations: SurfaceLocation[];
+    /**
+     * Marks a surface as externally consumable. It inherits the unit's zone:
+     * only meaningful when the unit's {@link PublicationZone} is `external`.
+     */
+    externallyPublished?: boolean;
+    /** Unknown/forward-compatible fields preserved verbatim on round-trip. */
+    unknownFields?: JsonObject;
+};
+export type ComponentSurfaceDescriptor = SurfaceCommon & {
+    kind: 'component';
+};
+export type RouteSurfaceDescriptor = SurfaceCommon & {
+    kind: 'route';
+};
+export type ApiSurfaceDescriptor = SurfaceCommon & {
+    kind: 'api';
+    protocol: ApiProtocol;
+};
+export type BackendSurfaceDescriptor = SurfaceCommon & {
+    kind: 'backend';
+};
+export type SurfaceDescriptor = ComponentSurfaceDescriptor | RouteSurfaceDescriptor | ApiSurfaceDescriptor | BackendSurfaceDescriptor;
+export type DeliveryUnitKind = 'microvertical' | 'shell' | 'horizontal-remote';
+/**
+ * The canonical authoring shape for one indivisible delivery unit. All surfaces
+ * derive from the single `sourceRevision` / `buildMarker` identity root
+ * (ADR-0019 invariants 1-2). This is a superset of today's v1 `WorkspaceApp`;
+ * see {@link projectDeliveryUnitToV1} for the lossy down-projection.
+ */
+export type DeliveryUnitDescriptor = {
+    unitId: string;
+    kind: DeliveryUnitKind;
+    owner: DeliveryUnitOwner;
+    sourceRevision: string;
+    buildMarker: string;
+    baselineCohort: BaselineCohort;
+    /** Defaults to `{ zone: 'coordinated' }` when omitted. */
+    publicationZone?: PublicationZone;
+    surfaces: SurfaceDescriptor[];
+    /** Unknown/forward-compatible fields preserved verbatim on round-trip. */
+    unknownFields?: JsonObject;
+};
+/**
+ * A resolved surface. It carries NO build marker of its own: the marker lives
+ * once on the {@link ResolvedDeliveryUnit}, so a resolver structurally cannot
+ * mix locations from different markers (ADR-0019 §3, invariant 3).
+ */
+export type ResolvedSurface = {
+    surfaceId: string;
+    kind: SurfaceKind;
+    locations: SurfaceLocation[];
+};
+export type CompatibilityStatus = 'compatible' | 'incompatible' | 'degraded';
+export type CompatibilityVerdict = {
+    status: CompatibilityStatus;
+    /** Baseline cohort id the verdict was computed against. */
+    baselineCohortId: string;
+    reason?: string;
+};
+/**
+ * Atomic resolution result. Every platform location for the unit is resolved
+ * together against ONE `buildMarker` / `sourceRevision`. There is no partial
+ * shape: a resolver returns a whole {@link ResolvedDeliveryUnit} or a typed
+ * failure — never a per-surface mix of markers. This shape is the W5/W7
+ * contract checkpoint.
+ */
+export type ResolvedDeliveryUnit = {
+    unitId: string;
+    buildMarker: string;
+    sourceRevision: string;
+    baselineCohortId: string;
+    surfaces: ResolvedSurface[];
+    compatibility: CompatibilityVerdict;
+};
+/**
+ * Parsed form of a SurfaceRef. Canonical string form is `unitId#surfaceId`
+ * with an optional `@vN` major suffix. See `packages/toolkit/create/delivery-unit-schema-SPEC.md` for the EBNF.
+ */
+export type ParsedSurfaceRef = {
+    unitId: string;
+    surfaceId: string;
+    /** External-major selector. Absent means "the coordinated-zone surface". */
+    major?: number;
+};
+export type SurfaceRefParseError = {
+    code: 'empty';
+} | {
+    code: 'missing-surface-separator';
+} | {
+    code: 'multiple-surface-separators';
+} | {
+    code: 'empty-unit-id';
+} | {
+    code: 'invalid-unit-id';
+    segment: string;
+} | {
+    code: 'empty-surface-id';
+} | {
+    code: 'invalid-surface-id';
+} | {
+    code: 'empty-major';
+} | {
+    code: 'invalid-major';
+    value: string;
+};
+export type SurfaceRefParseResult = {
+    ok: true;
+    ref: ParsedSurfaceRef;
+} | {
+    ok: false;
+    error: SurfaceRefParseError;
+};
+/**
+ * Parse a canonical SurfaceRef string. Total function: every rejection is a
+ * typed {@link SurfaceRefParseError}; never throws.
+ */
+export declare function parseSurfaceRef(input: string): SurfaceRefParseResult;
+/**
+ * Render a {@link ParsedSurfaceRef} back to its canonical string form.
+ *
+ * Direct inputs are checked against the same invariant as parsed references,
+ * so this formatter cannot emit a string that {@link parseSurfaceRef} rejects.
+ */
+export declare function formatSurfaceRef(ref: ParsedSurfaceRef): string;
+/** Apply the zone default (coordinated) invariant. */
+export declare function resolvePublicationZone(zone: PublicationZone | undefined): PublicationZone;
+/**
+ * Parse a JSON object into a {@link DeliveryUnitDescriptor}, capturing any
+ * unrecognised top-level and per-surface keys into `unknownFields` so a later
+ * {@link serializeDeliveryUnitDescriptor} can round-trip them verbatim.
+ *
+ * This is contract-shape capture, not strict validation (that is W3's job);
+ * known fields are trusted to already have their declared shapes.
+ */
+export declare function parseDeliveryUnitDescriptor(source: JsonObject): DeliveryUnitDescriptor;
+/**
+ * Serialize a {@link DeliveryUnitDescriptor} back to a JSON object. Preserved
+ * `unknownFields` are spread back at their original level; known keys always
+ * win over a colliding unknown key.
+ */
+export declare function serializeDeliveryUnitDescriptor(descriptor: DeliveryUnitDescriptor): JsonObject;
+/**
+ * Generator-only fields that have no source in the canonical descriptor (port
+ * assignment, directory layout, package identity, ownership metadata). The
+ * descriptor deliberately does not own these; the v1 projection needs them to
+ * reconstruct today's `WorkspaceApp` / `DeliveryUnitRecord`.
+ */
+export type V1ProjectionContext = {
+    /**
+     * Which v1 wire vocabulary is being projected onto. Strict legacy v1 only
+     * carries the historical WorkspaceApp fields; extended-v1 also carries the
+     * additive delivery-unit discriminators introduced by the workspace
+     * topology format.
+     */
+    mode?: V1ProjectionMode;
+    directory: string;
+    packageSuffix: string;
+    displayName: string;
+    portEnv: string;
+    port: number;
+    mfName: string;
+    ownership: Ownership;
+    packageName: string;
+    version: string;
+};
+/**
+ * The two v1 wire vocabularies understood by the projection pair.
+ *
+ * `strict-legacy` is the original v1 shape and intentionally rejects values
+ * that would be silently collapsed by it. `extended-v1` is still schema
+ * version 1, but permits the additive `deliveryUnitKind` and `api.protocol`
+ * fields used by the UltraModern topology/config readers.
+ */
+export type V1ProjectionMode = 'strict-legacy' | 'extended-v1';
+export type DeliveryUnitV1Projection = {
+    app: WorkspaceApp;
+    deliveryUnitRecord: DeliveryUnitRecord;
+    /** Unknown descriptor-level fields, preserved for lossless re-serialization. */
+    preservedUnknownFields: JsonObject;
+};
+/**
+ * Down-project a canonical {@link DeliveryUnitDescriptor} onto today's v1
+ * `WorkspaceApp` + `DeliveryUnitRecord` shapes. Pure and total.
+ *
+ * Invariant (schema-only migration preserves markers): `buildMarker`,
+ * `sourceRevision`, and `unitId` flow straight through from the descriptor and
+ * are never regenerated here. See `packages/toolkit/create/delivery-unit-schema-SPEC.md` for the field-by-field table.
+ *
+ * NOT wired into any generator path.
+ */
+export declare function projectDeliveryUnitToV1(descriptor: DeliveryUnitDescriptor, context: V1ProjectionContext): DeliveryUnitV1Projection;
+/** Compile-time exhaustiveness guard for discriminated-union switches. */
+export declare function assertNever(value: never): never;
+export {};

package/dist/types/ultramodern-workspace/delivery-unit-schema/up-projection.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Canonical MicroVertical delivery contracts (W4) — v1 UP-projection.
+ *
+ * This module completes the round-trip that the down-projection in
+ * `./types.ts` opened. Where {@link projectDeliveryUnitToV1} maps a canonical
+ * {@link DeliveryUnitDescriptor} DOWN onto today's v1 `WorkspaceApp` +
+ * `DeliveryUnitRecord`, {@link projectV1ToDeliveryUnit} maps a v1
+ * `WorkspaceApp` UP into the canonical descriptor. The two compose so that
+ * "every current fixture round-trips v1 -> canonical -> v1" (MicroVertical
+ * Phase-1 exit criterion).
+ *
+ * Generator paths consume the projection helpers for grammar-safe surface
+ * identity and owner/representability checks; the schema functions themselves
+ * remain pure and side-effect free.
+ *
+ * Binding vocabulary: root `CONTEXT.md`, ADR-0019 (Federated Loading, Unified
+ * Delivery), ADR-0020 (Zoned Surface Versioning). See the SPEC §5 mapping
+ * table read in reverse.
+ *
+ * TS constraint: plain types + pure functions only. This file is scanned by
+ * `tsgo-boundary.test.ts`; it must never import TypeScript compiler APIs.
+ */
+import type { Ownership, WorkspaceApi, WorkspaceApp } from '../types';
+import type { ApiProtocol, ApiSurfaceDescriptor, BaselineCohort, ComponentSurfaceDescriptor, DeliveryUnitDescriptor, DeliveryUnitOwner, RouteSurfaceDescriptor, V1ProjectionMode } from './types';
+/**
+ * The identity-root and platform-baseline facts that a v1 `WorkspaceApp` does
+ * NOT carry but a canonical {@link DeliveryUnitDescriptor} requires. This is
+ * the mirror image of the down-projection's `V1ProjectionContext`: the down
+ * context supplies generator-only fields the descriptor deliberately does not
+ * own (port, directory, package identity, ownership); this up context supplies
+ * the canonical identity root the v1 app never had.
+ *
+ * Composition contract: given `record = createDeliveryUnitRecord(scope, app)`
+ * (or an existing `DeliveryUnitRecord`), thread `record.buildMarker`,
+ * `record.sourceRevision`, and the same `scope` through here so the descriptor
+ * this produces reconstructs `record.unitId` verbatim. `buildMarker`,
+ * `sourceRevision`, and `unitId` therefore survive a v1 -> canonical -> v1
+ * pass untouched (SPEC §5 invariant 5, marker preservation).
+ */
+export type V1UpProjectionContext = {
+    /**
+     * The v1 vocabulary being read. In `extended-v1`, additive fields already
+     * present on the WorkspaceApp are authoritative for kind/protocol; strict
+     * legacy mode deliberately ignores them and exposes their loss through the
+     * representability guard.
+     */
+    mode?: V1ProjectionMode;
+    /** Package/topology scope. `unitId` = `${scope}/${app.domain ?? app.id}`. */
+    scope: string;
+    /** Identity root: exact source revision, threaded, never regenerated. */
+    sourceRevision: string;
+    /** Identity root: exact build marker, threaded, never regenerated. */
+    buildMarker: string;
+    /**
+     * Composition-time platform baseline pins. v1 has no cohort concept (the
+     * cohort is advanced platform-wide, never per-vertical), so the caller must
+     * supply the resolved cohort this unit was composed against.
+     */
+    baselineCohort: BaselineCohort;
+    /**
+     * Protocol for the app's HTTP api surface, if any. Defaults to `rest`:
+     * today's v1 `WorkspaceApi` is only ever an HTTP REST prefix, so `rest` is
+     * the faithful reading of current reality (SPEC §1: api surfaces carry a
+     * protocol; v1 cannot distinguish rpc/graphql).
+     */
+    apiProtocol?: ApiProtocol;
+};
+/**
+ * Map a v1 {@link Ownership} block onto the canonical single {@link
+ * DeliveryUnitOwner}.
+ *
+ * Owner honouring (G3): when the v1 `Ownership` carries an explicit `owner`
+ * attribution (opt-in — the way v1 records an `agent` / `agent-team` owner),
+ * that attribution IS the canonical owner and is passed through verbatim
+ * (`kind` + `id` + optional `contact`). Only when no explicit owner was set
+ * does this fall back to the neutral human-team default: `kind: 'team'`, `id`
+ * from `ownership.team`, `contact` from `ownership.slack`. The down-projection
+ * writes a non-team owner back into `ownership.owner`, so agent / agent-team
+ * owners round-trip faithfully through the projection pair.
+ */
+export declare function ownershipToOwner(ownership: Ownership): DeliveryUnitOwner;
+/** Derive a canonical, SurfaceRef-valid `surfaceId` from an MF expose key. */
+export declare function exposeSurfaceId(key: string): string;
+/**
+ * Map a single v1 expose onto a component-or-route surface.
+ *
+ * Route heuristic: an expose whose key or local module path mentions `route`
+ * is a `route` surface; everything else is a `component`. The exposed local
+ * module path (e.g. `./src/...`) is a build detail the canonical model
+ * deliberately abstracts away, so it is dropped; the surface's single
+ * `browser-mf` location points at the app's MF manifest (derived from
+ * `app.port`, the only address a v1 app exposes for its browser bundle).
+ */
+export declare function exposeSurface(app: WorkspaceApp, key: string, value: string): ComponentSurfaceDescriptor | RouteSurfaceDescriptor;
+/**
+ * Map a v1 API descriptor onto the canonical API surface vocabulary.
+ *
+ * `stem` -> `surfaceId`; `prefix` -> a single `http` location `address`;
+ * `protocol` from context (default `rest`). `consumedBy` has no canonical
+ * home: it is a v1 emergent graph fact (SPEC §5 marks it non-projected), so it
+ * is dropped here and the down-projection re-zeroes it to `[]`.
+ *
+ * Callers that know the concrete transport mount (for example RPC, which is
+ * mounted below the API prefix) may provide its address explicitly. Keeping
+ * the surface id/protocol/location construction here prevents generator
+ * paths from re-deriving a second canonical API surface shape.
+ */
+export declare function apiSurface(api: WorkspaceApi, protocol: ApiProtocol, address?: string): ApiSurfaceDescriptor;
+/**
+ * Up-project a v1 `WorkspaceApp` into a canonical {@link
+ * DeliveryUnitDescriptor}. Pure and total: `WorkspaceApp.kind` is only
+ * `shell | vertical`, so this never throws and never produces the
+ * v1-unrepresentable `horizontal-remote` kind or the `external` zone.
+ *
+ * The `publicationZone` is always `{ zone: 'coordinated' }`: v1 has no way to
+ * express external publication (ADR-0020), so a v1 app is always coordinated.
+ *
+ * Marker preservation: `unitId` = `${context.scope}/${app.domain ?? app.id}`
+ * (identical to `createDeliveryUnitRecord`), and `buildMarker` /
+ * `sourceRevision` are threaded straight from `context`, never regenerated.
+ *
+ * Generator paths may consume this projection for canonical surface metadata;
+ * the projection remains pure and does not mutate the v1 app.
+ */
+export declare function projectV1ToDeliveryUnit(app: WorkspaceApp, context: V1UpProjectionContext): DeliveryUnitDescriptor;
+/**
+ * The reasons a canonical descriptor cannot be faithfully represented in v1.
+ * The down-projection in `./types.ts` degrades ALL of these silently, so this
+ * guard exhaustively detects every canonical construct the v1 shape cannot
+ * carry and lets callers fail loudly INSTEAD of degrading silently:
+ *
+ * - `horizontal-remote-kind`: v1 collapses `horizontal-remote` to `vertical`.
+ * - `external-zone`: v1 has no publication-zone field (ADR-0020).
+ * - `component-or-route-surface`: the down-projection reconstructs no
+ *   `exposes`, so every component/route surface is dropped.
+ * - `backend-surface`: v1 has no backend-surface vocabulary at all.
+ * - `multiple-api-surfaces`: v1 carries at most ONE `WorkspaceApi`; the
+ *   down-projection keeps the first api surface and drops the rest.
+ * - `non-rest-protocol`: v1 `WorkspaceApi` is an HTTP REST prefix; `rpc` /
+ *   `graphql` protocols are dropped (the up-projection re-defaults to
+ *   `rest`).
+ * - `unsupported-surface-shape`: an api surface whose shape v1 cannot carry —
+ *   anything other than exactly one `http` location, or per-surface
+ *   `externallyPublished` / `unknownFields` metadata.
+ * - `unknown-fields`: the descriptor carries top-level `unknownFields`. v1 has
+ *   nowhere to store them in-band — the down-projection returns them
+ *   out-of-band (`preservedUnknownFields`), so a v1 shape cannot reproduce the
+ *   descriptor byte-for-byte in a single canonical value.
+ * - `non-canonical-zone`: the descriptor's `publicationZone` is not exactly the
+ *   canonical `{ zone: 'coordinated' }` the up-projection always re-emits. A
+ *   descriptor with NO `publicationZone` (down drops the field, up re-adds an
+ *   explicit coordinated zone) or a `coordinated` zone carrying extra fields is
+ *   therefore not round-trip-faithful.
+ */
+export type V1UnrepresentableReason = 'horizontal-remote-kind' | 'external-zone' | 'component-or-route-surface' | 'backend-surface' | 'multiple-api-surfaces' | 'non-rest-protocol' | 'unsupported-surface-shape' | 'unknown-fields' | 'non-canonical-zone';
+export type V1RepresentabilityResult = {
+    representable: true;
+} | {
+    representable: false;
+    code: 'unrepresentable-in-v1';
+    reason: V1UnrepresentableReason;
+};
+/**
+ * A typed error for v1-unrepresentable cases. `code` is always
+ * `'unrepresentable-in-v1'`; `reason` narrows which invariant was violated.
+ */
+export declare class V1UnrepresentableError extends Error {
+    readonly code: 'unrepresentable-in-v1';
+    readonly reason: V1UnrepresentableReason;
+    constructor(reason: V1UnrepresentableReason);
+}
+/**
+ * Total check: is a canonical descriptor faithfully representable in v1?
+ * Returns a typed result rather than throwing. Exhaustive over the loss set
+ * of `projectDeliveryUnitToV1` (see {@link V1UnrepresentableReason}); the
+ * first detected reason is reported, in a deterministic order (unit-level
+ * kind, unknown-fields, zone, then surfaces in declaration order).
+ *
+ * The round-trip law rests on this guard: for descriptors this function
+ * accepts, canonical -> v1 -> canonical is lossless on every
+ * representability-covered field.
+ */
+export declare function checkV1Representable(descriptor: DeliveryUnitDescriptor, mode?: V1ProjectionMode): V1RepresentabilityResult;
+/**
+ * Assert v1 representability, throwing a typed {@link V1UnrepresentableError}
+ * for any descriptor carrying a construct the v1 shape cannot represent,
+ * rather than letting the down-projection degrade it silently.
+ */
+export declare function assertV1Representable(descriptor: DeliveryUnitDescriptor, mode?: V1ProjectionMode): void;

package/dist/types/ultramodern-workspace/delivery-unit-stamp.d.ts

@@ -0,0 +1,3 @@
+import type { WorkspaceApp } from './types';
+/** Stamp one compact-config or reference-topology app with canonical identity. */
+export declare function stampDeliveryUnitIdentity(entry: Record<string, any>, scope: string, app: WorkspaceApp): void;

package/dist/types/ultramodern-workspace/delivery-unit-sync.d.ts

@@ -0,0 +1,6 @@
+type SyncContext = {
+    workspaceRoot: string;
+    invocationCwd: string;
+};
+export declare function runSyncDeliveryUnit(args: string[], context: SyncContext): number;
+export {};

package/dist/types/ultramodern-workspace/delivery-unit.d.ts

@@ -0,0 +1,8 @@
+import { type DeliveryUnitRecord, deliveryUnitContractBlock } from '@modern-js/utils/universal';
+import type { WorkspaceApp } from './types';
+export declare function createBuildMarker(scope: string, app: {
+    id: string;
+    packageSuffix: string;
+}): string;
+export { deliveryUnitContractBlock };
+export declare function createDeliveryUnitRecord(scope: string, app: WorkspaceApp): DeliveryUnitRecord;

package/dist/types/ultramodern-workspace/demo-components.d.ts

@@ -1,9 +1,20 @@
 import type { WorkspaceApp } from './types';
-export declare function createShellPage(remotes?: WorkspaceApp[]): string;
-export declare function createShellRemoteComponents(scope: string, remotes?: WorkspaceApp[]): string;
+export declare function createShellPage(shell: WorkspaceApp, remotes?: WorkspaceApp[]): string;
+export declare function createShellRemoteComponents(shell: WorkspaceApp, remotes?: WorkspaceApp[]): string;
+export declare function createShellWorkerRemoteComponents(shell: WorkspaceApp, remotes?: WorkspaceApp[]): string;
+/**
+ * Generates the environment-specific primitive registry used by custom hosts.
+ * The browser/Node file contains native MF loaders. Cloudflare's `.worker.tsx`
+ * resolution selects the sibling registry, which contains only distributed
+ * service-binding boundaries and therefore cannot bundle remote UI source.
+ */
+export declare function createFederatedComponentsRegistry(scope: string, host: WorkspaceApp, remotes: WorkspaceApp[], worker?: boolean): string;
 export declare function createRemotePage(app: WorkspaceApp): string;
 export declare function createLayout(appId: string): string;
 export declare function createRemoteEntry(app: WorkspaceApp): string;
-export declare function createRemoteWidget(app: WorkspaceApp): string;
+export declare function createRemoteWidgetFragmentPage(app: WorkspaceApp): string;
+export declare function createRemoteExposeFragmentPage(app: WorkspaceApp, expose: string): string;
 export declare function createRemoteExposeComponent(app: WorkspaceApp, expose: string): string;
 export declare function remoteComponentOutputPath(app: WorkspaceApp, expose: string): string | undefined;
+export type GeneratedNavigationSurfaceKind = 'demo-component' | 'shell-frame';
+export declare function regenerateGeneratedNavigationSurface(source: string, kind: GeneratedNavigationSurfaceKind): string;

package/dist/types/ultramodern-workspace/descriptors.d.ts

@@ -1,17 +1,37 @@
-import type { Ownership, WorkspaceApi, WorkspaceApp } from './types';
+import type { Ownership, VerticalApiProtocol, VerticalPreset, WorkspaceApi, WorkspaceApp } from './types';
 export declare const ULTRAMODERN_CONFIG_PATH = ".modernjs/ultramodern.json";
+export declare function distributedSsrExposes(app: WorkspaceApp): string[];
+export declare function distributedSsrFragmentSlug(expose: string): string;
+export declare function distributedSsrFragmentRoute(expose: string): string;
 export declare const shellApp: WorkspaceApp;
-export declare function createShellHost(remotes?: WorkspaceApp[]): WorkspaceApp;
+export declare function createShellHost(remotes?: WorkspaceApp[], verticalRefs?: string[]): WorkspaceApp;
 export declare const sharedPackages: {
     id: string;
     directory: string;
     description: string;
 }[];
 export declare function createNeutralOwnership(id: string, tier?: string): Ownership;
-export declare function createVerticalDescriptor(name: string, port: number): WorkspaceApp;
+export type CreateVerticalDescriptorOptions = {
+    /** Generation preset (G2a). Defaults to `full-stack`. */
+    preset?: VerticalPreset;
+    /** API protocol (G7a). Defaults to `rest`. */
+    apiProtocol?: VerticalApiProtocol;
+    /** Generate a Horizontal Remote delivery unit (G2H) instead of a vertical. */
+    horizontalRemote?: boolean;
+};
+export declare function createVerticalDescriptor(name: string, port: number, options?: CreateVerticalDescriptorOptions): WorkspaceApp;
 export declare function appHasApi(app: WorkspaceApp): app is WorkspaceApp & {
     api: WorkspaceApi;
 };
+/**
+ * Whether an app emits browser/UI artifacts (routes, page/layout, public-web
+ * surfaces, Tailwind, browser Module Federation). True for the shell and for
+ * `full-stack` / `ui-only` verticals; false only for an `api-only` (headless)
+ * vertical (G2a).
+ */
+export declare function appEmitsBrowserUi(app: WorkspaceApp): boolean;
+/** The API protocol for an app's API surface (G7a). Defaults to `rest`. */
+export declare function resolveApiProtocol(app: WorkspaceApp): VerticalApiProtocol;
 export declare function resolveApiPrefix(target: {
     id: string;
     api?: WorkspaceApi;
@@ -27,6 +47,10 @@ export declare function remoteDependencyAlias(remote: WorkspaceApp): string;
 export declare function zephyrRemoteDependency(scope: string, remote: WorkspaceApp): string;
 export declare function resolveRemoteRefs(app: WorkspaceApp, remotes?: WorkspaceApp[]): WorkspaceApp[];
 export declare function createRemoteManifestEnv(remote: WorkspaceApp): string;
+export declare function createBackendFederationManifestEnv(remote: WorkspaceApp): string;
+export declare function createBackendFederationName(app: WorkspaceApp): string;
+export declare function createBackendFederationManifestUrl(app: WorkspaceApp): string;
+export declare function createBackendFederationContainerEntry(app: WorkspaceApp): string;
 export declare function createModuleFederationRemoteContracts(app: WorkspaceApp, remotes?: WorkspaceApp[]): {
     id: string;
     alias: string;

package/dist/types/ultramodern-workspace/effect-diagnostics.d.ts

@@ -0,0 +1 @@
+export declare const effectDiagnostics: string[];

package/dist/types/ultramodern-workspace/fs-io.d.ts

@@ -1,19 +1,13 @@
 import type { JsonValue } from './types';
 export declare const createPackageRoot: string;
-export declare const workspaceTemplateDir: any;
-export declare const fileTemplatesDir: any;
+export declare const workspaceTemplateDir: string;
 export declare function readFileTemplate(relativePath: string): string;
 export declare function renderFileTemplate(relativePath: string, data: Record<string, string>): string;
-export declare function assertSafeRelativePath(relativePath: string): void;
-export declare function ensureInsideRoot(root: string, targetPath: string): void;
 export declare function writeFile(targetDir: string, relativePath: string, content: string): void;
 export declare function writeFileReplacing(targetDir: string, relativePath: string, content: string): void;
 export declare function writeJson(targetDir: string, relativePath: string, value: JsonValue): void;
 export declare function formatGeneratedWorkspaceFiles(targetDir: string, relativePaths?: readonly string[]): void;
 export declare function renderTemplate(template: string, data: Record<string, string>): string;
-export declare function collectTemplateFiles(dir: string): string[];
-export declare function hashFile(filePath: string): string;
-export declare function hashTemplateTree(dir: string): string;
-export declare function copyRootTemplate(targetDir: string, data: Record<string, string>): void;
+export declare function copyRootTemplate(targetDir: string, data: Record<string, string>, excludedRelativePaths?: ReadonlySet<string>): void;
 export declare function readJsonFile(filePath: string): Record<string, any>;
 export declare function writeJsonFile(filePath: string, value: JsonValue): void;

package/dist/types/ultramodern-workspace/generation-result.d.ts

@@ -1,5 +1,6 @@
 import type { ResolvedPackageSource, UltramodernGenerationOperation, UltramodernGenerationResult, UltramodernGenerationWarning, WorkspaceApp } from './types';
-export type FileSnapshot = Map<string, string>;
+export declare const ignoredSnapshotDirectories: Set<string>;
+type FileSnapshot = Map<string, string>;
 export declare function createFileSnapshot(root: string): FileSnapshot;
 export declare function diffFileSnapshots(before: FileSnapshot, after: FileSnapshot): Pick<UltramodernGenerationResult, 'createdPaths' | 'rewrittenPaths'>;
 export declare function createGenerationResult(options: {
@@ -12,3 +13,4 @@ export declare function createGenerationResult(options: {
     rewrittenPaths: string[];
     warnings?: UltramodernGenerationWarning[];
 }): UltramodernGenerationResult;
+export {};

package/dist/types/ultramodern-workspace/index.d.ts

@@ -1,6 +1,11 @@
+export { addUltramodernShell, planUltramodernShell } from './add-shell';
 export { addUltramodernVertical, planUltramodernVertical, } from './add-vertical';
 export type { UltramodernBridgeConfig, UltramodernBridgeConfigInput, UltramodernBridgeGate, UltramodernBridgeGateInput, UltramodernBridgeLockfilePolicy, UltramodernBridgeTestAlias, UltramodernBridgeWorkspacePackage, UltramodernBridgeWorkspacePackageInput, UltramodernEnabledBridgeConfigInput, } from './bridge-config';
 export { normalizeUltramodernBridgeConfig } from './bridge-config';
-export type { AddUltramodernVerticalOptions, UltramodernCodeSmithOverlay, UltramodernCodeSmithOverlayRuntimeConfig, UltramodernGeneratedAppDescriptor, UltramodernGeneratedContractChange, UltramodernGenerationOperation, UltramodernGenerationResult, UltramodernGenerationWarning, UltramodernJsonMutation, UltramodernShellDependencyChange, UltramodernVerticalPlan, UltramodernWorkspaceOptions, } from './types';
+export type { OverlayBaselineViolation } from './overlay-baseline-guard';
+export { BASELINE_DEPENDENCY_PINS, OverlayBaselineRelaxationError, } from './overlay-baseline-guard';
+export { SHARED_ULTRAMODERN_WORKSPACE_PATCH_FILES } from './shared-patches';
+export { createShellDescriptor, PRIMARY_SHELL_ID, resolveConfiguredAdditionalShells, } from './shells';
+export type { AddUltramodernShellOptions, AddUltramodernVerticalOptions, UltramodernCodeSmithOverlay, UltramodernCodeSmithOverlayRuntimeConfig, UltramodernGeneratedAppDescriptor, UltramodernGeneratedContractChange, UltramodernGenerationOperation, UltramodernGenerationResult, UltramodernGenerationWarning, UltramodernJsonMutation, UltramodernShellDependencyChange, UltramodernVerticalPlan, UltramodernWorkspaceOptions, } from './types';
 export { ultramodernWorkspaceVersions } from './versions';
 export { generateUltramodernWorkspace } from './write-workspace';