@paul-portfolio/work-portfolio-contract 0.0.0-stage → 1.0.0

package/dist/catalog.d.ts

@@ -0,0 +1,79 @@
+import { z } from "zod";
+/**
+ * The work-portfolio catalog: past projects and the demoable features under
+ * them. The remote owns it and serves it as catalog.json; the host only ever
+ * reads it through this schema.
+ */
+/** Visual accent each project's demos carry inside the stage. */
+export declare const AccentThemeSchema: z.ZodObject<{
+    accent: z.ZodString;
+    surface: z.ZodString;
+    font: z.ZodEnum<{
+        sans: "sans";
+        mono: "mono";
+    }>;
+}, z.core.$strip>;
+/** One of the past projects. Names are public-safe, never the real ones. */
+export declare const WorkProjectSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    blurb: z.ZodString;
+    stack: z.ZodString;
+    accent: z.ZodObject<{
+        accent: z.ZodString;
+        surface: z.ZodString;
+        font: z.ZodEnum<{
+            sans: "sans";
+            mono: "mono";
+        }>;
+    }, z.core.$strip>;
+    cutFeatures: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+/** One demoable feature, shown in the bottom ticker. */
+export declare const WorkFeatureSchema: z.ZodObject<{
+    slug: z.ZodString;
+    projectId: z.ZodString;
+    title: z.ZodString;
+    tagline: z.ZodString;
+    icon: z.ZodString;
+    flagship: z.ZodOptional<z.ZodBoolean>;
+    explainer: z.ZodObject<{
+        did: z.ZodString;
+        stack: z.ZodString;
+        mocked: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const CatalogSchema: z.ZodObject<{
+    projects: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        blurb: z.ZodString;
+        stack: z.ZodString;
+        accent: z.ZodObject<{
+            accent: z.ZodString;
+            surface: z.ZodString;
+            font: z.ZodEnum<{
+                sans: "sans";
+                mono: "mono";
+            }>;
+        }, z.core.$strip>;
+        cutFeatures: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+    features: z.ZodArray<z.ZodObject<{
+        slug: z.ZodString;
+        projectId: z.ZodString;
+        title: z.ZodString;
+        tagline: z.ZodString;
+        icon: z.ZodString;
+        flagship: z.ZodOptional<z.ZodBoolean>;
+        explainer: z.ZodObject<{
+            did: z.ZodString;
+            stack: z.ZodString;
+            mocked: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type AccentTheme = z.infer<typeof AccentThemeSchema>;
+export type WorkProject = z.infer<typeof WorkProjectSchema>;
+export type WorkFeature = z.infer<typeof WorkFeatureSchema>;
+export type Catalog = z.infer<typeof CatalogSchema>;

package/dist/catalog.js

@@ -0,0 +1,75 @@
+import { z } from "zod";
+/**
+ * The work-portfolio catalog: past projects and the demoable features under
+ * them. The remote owns it and serves it as catalog.json; the host only ever
+ * reads it through this schema.
+ */
+/** Visual accent each project's demos carry inside the stage. */
+export const AccentThemeSchema = z.object({
+    /** primary accent color, hex */
+    accent: z.string(),
+    /** translucent surface tint used behind demo content */
+    surface: z.string(),
+    /** typography flavor for the demo surface */
+    font: z.enum(["sans", "mono"]),
+});
+/** One of the past projects. Names are public-safe, never the real ones. */
+export const WorkProjectSchema = z.object({
+    id: z.string().min(1),
+    /** anonymized public name shown in the top ticker */
+    name: z.string().min(1),
+    /** one-liner for the explainer window */
+    blurb: z.string(),
+    /** original stack, described without identifying details */
+    stack: z.string(),
+    accent: AccentThemeSchema,
+    /** features that did not make the ticker, listed in the explainer */
+    cutFeatures: z.array(z.string()),
+});
+/** One demoable feature, shown in the bottom ticker. */
+export const WorkFeatureSchema = z.object({
+    /** url-safe id used for ?feature= deep links, so it never changes once shipped */
+    slug: z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
+    projectId: z.string().min(1),
+    title: z.string().min(1),
+    /** short line shown on the chip and stage header */
+    tagline: z.string(),
+    /** small emoji icon shown on the chip */
+    icon: z.string(),
+    /** flagship demos get more depth than vignettes */
+    flagship: z.boolean().optional(),
+    explainer: z.object({
+        /** what the feature did in the original app */
+        did: z.string(),
+        /** what it was built with originally */
+        stack: z.string(),
+        /** what is real vs faked in this reconstruction */
+        mocked: z.string(),
+    }),
+});
+export const CatalogSchema = z
+    .object({
+    projects: z.array(WorkProjectSchema),
+    features: z.array(WorkFeatureSchema),
+})
+    .superRefine((catalog, ctx) => {
+    const projectIds = new Set(catalog.projects.map((p) => p.id));
+    const seen = new Set();
+    catalog.features.forEach((feature, index) => {
+        if (seen.has(feature.slug)) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["features", index, "slug"],
+                message: `duplicate slug "${feature.slug}"`,
+            });
+        }
+        seen.add(feature.slug);
+        if (!projectIds.has(feature.projectId)) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["features", index, "projectId"],
+                message: `unknown project "${feature.projectId}"`,
+            });
+        }
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Everything that crosses the boundary between paul-explore (the host) and
+ * the work-portfolio remote. Both sides type-check against this package, and
+ * nothing else is shared between them except the design-system tokens.
+ */
+export { AccentThemeSchema, WorkProjectSchema, WorkFeatureSchema, CatalogSchema, type AccentTheme, type WorkProject, type WorkFeature, type Catalog, } from "./catalog.js";
+/**
+ * The contract's major version. The host refuses a remote built against a
+ * different major and shows its fallback instead, so a breaking change ships
+ * as: host learns both majors, remote moves, host drops the old one.
+ */
+export declare const CONTRACT_VERSION = 1;
+/** Whether a remote's declared contract version is one this build can mount. */
+export declare function isCompatibleContract(version: unknown): boolean;
+/** A referral link, as portfolio_api returns it. */
+export type Referral = {
+    slug: string;
+    targetPath: string;
+    label: string | null;
+    url: string;
+    clicks: number;
+    createdAt: string;
+};
+export type ReferralStats = {
+    slug: string;
+    targetPath: string;
+    clicks: number;
+    recent: {
+        at: string;
+    }[];
+};
+export type CreateReferralInput = {
+    slug?: string;
+    targetPath?: string;
+    label?: string;
+};
+/**
+ * Capabilities the host lends the remote. The remote never learns an API URL
+ * or touches auth: it asks for data through these and the host decides how to
+ * fetch it. An API refusal rejects with an Error whose message is fit to show
+ * a user; an unreachable API rejects with a TypeError, the way fetch does, so
+ * the remote can tell "no" apart from "offline".
+ */
+export type HostServices = {
+    referrals: {
+        create(input: CreateReferralInput): Promise<Referral>;
+        stats(slug: string): Promise<ReferralStats>;
+        recordClick(slug: string): Promise<{
+            slug: string;
+            clicks: number;
+        }>;
+    };
+};
+/**
+ * What the host hands the remote on mount. The host owns the URL: the remote
+ * reads the starting feature from here and reports changes back, and never
+ * writes to history itself.
+ */
+export type HostContext = {
+    /** slug from ?feature=, or null for the intro card */
+    initialFeature: string | null;
+    /** called whenever the selected feature changes; null means the intro card */
+    onFeatureChange(slug: string | null): void;
+    services: HostServices;
+};
+export type MountHandle = {
+    /** re-render with part of the context replaced, e.g. a new initialFeature */
+    update(next: Partial<HostContext>): void;
+    /** tear everything down: React root, listeners, timers */
+    unmount(): void;
+};
+/** The shape of the module the remote exposes as "./mount". */
+export type RemoteModule = {
+    contractVersion: number;
+    /** the remote's own release, e.g. "1.4.0" */
+    version: string;
+    mount(el: HTMLElement, ctx: HostContext): MountHandle;
+};

package/dist/index.js

@@ -0,0 +1,16 @@
+/**
+ * Everything that crosses the boundary between paul-explore (the host) and
+ * the work-portfolio remote. Both sides type-check against this package, and
+ * nothing else is shared between them except the design-system tokens.
+ */
+export { AccentThemeSchema, WorkProjectSchema, WorkFeatureSchema, CatalogSchema, } from "./catalog.js";
+/**
+ * The contract's major version. The host refuses a remote built against a
+ * different major and shows its fallback instead, so a breaking change ships
+ * as: host learns both majors, remote moves, host drops the old one.
+ */
+export const CONTRACT_VERSION = 1;
+/** Whether a remote's declared contract version is one this build can mount. */
+export function isCompatibleContract(version) {
+    return typeof version === "number" && Math.floor(version) === CONTRACT_VERSION;
+}

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@paul-portfolio/work-portfolio-contract",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "The boundary between paul-explore and the work-portfolio micro-frontend: mount types, host services, and the catalog schema.",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gpbsumido/work-portfolio-mfe.git",
+    "directory": "packages/contract"
+  },
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.43",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.2",
+    "zod": "^4.3.6"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.