@ekanos/harness 0.24.0 → 0.26.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. package/README.md +3 -4
  2. package/dist/api-types.d.ts +98 -0
  3. package/dist/internal/components/approvals-tray.js +1 -1
  4. package/dist/internal/components/ask-assistant-bridge.js +2 -8
  5. package/dist/internal/components/connect-panel.js +414 -20
  6. package/dist/internal/components/dev-toolbar.js +3 -3
  7. package/dist/internal/components/docs-link.js +1 -1
  8. package/dist/internal/components/integration-badge.js +3 -3
  9. package/dist/internal/components/local-oauth-panel.js +28 -2
  10. package/dist/internal/components/provenance-banner.js +2 -2
  11. package/dist/internal/components/schema-form.js +1 -1
  12. package/dist/internal/components/surface-nav.js +20 -20
  13. package/dist/internal/components/widget-boundary.js +1 -7
  14. package/dist/internal/lib/console-client.d.ts +22 -5
  15. package/dist/internal/lib/console-client.js +32 -6
  16. package/dist/internal/lib/console-context.js +14 -2
  17. package/dist/internal/lib/console-types.d.ts +11 -1
  18. package/dist/internal/lib/experience-runtime.d.ts +20 -0
  19. package/dist/internal/lib/experience-runtime.js +16 -1
  20. package/dist/internal/lib/oauth-connect-href.d.ts +9 -0
  21. package/dist/internal/lib/oauth-connect-href.js +14 -0
  22. package/dist/internal/lib/run-log-view.js +1 -0
  23. package/dist/internal/lib/trigger-contract.d.ts +19 -0
  24. package/dist/internal/lib/trigger-runner.js +4 -1
  25. package/dist/internal/routes/experience-page-host.d.ts +5 -1
  26. package/dist/internal/routes/experience-page-host.js +9 -8
  27. package/dist/internal/routes/repo-home-page.js +1 -1
  28. package/dist/internal/routes/repo-layout.js +3 -5
  29. package/dist/internal/routes/root-layout.d.ts +0 -1
  30. package/dist/internal/routes/root-layout.js +2 -4
  31. package/dist/internal/routes/tile-page.js +1 -1
  32. package/dist/internal/routes/triggers-page.js +30 -2
  33. package/dist/internal/server/activation-credentials.d.ts +26 -0
  34. package/dist/internal/server/activation-credentials.js +56 -0
  35. package/dist/internal/server/api-router.js +63 -5
  36. package/dist/internal/server/console-state.d.ts +25 -0
  37. package/dist/internal/server/console-state.js +44 -0
  38. package/dist/internal/server/ekanos-api-router.js +168 -4
  39. package/dist/internal/server/live-context.js +2 -1
  40. package/dist/internal/server/live-invoker.js +10 -2
  41. package/dist/internal/server/local-secrets.d.ts +47 -0
  42. package/dist/internal/server/local-secrets.js +111 -2
  43. package/dist/internal/server/local-state.d.ts +8 -2
  44. package/dist/internal/server/local-state.js +26 -9
  45. package/dist/internal/server/nonce-store.d.ts +2 -0
  46. package/dist/internal/server/oauth-connections.d.ts +45 -0
  47. package/dist/internal/server/oauth-connections.js +69 -0
  48. package/dist/internal/server/oauth-loop.d.ts +1 -1
  49. package/dist/internal/server/oauth-loop.js +4 -1
  50. package/dist/internal/server/oauth-persistence.d.ts +13 -0
  51. package/dist/internal/server/oauth-persistence.js +28 -0
  52. package/dist/internal/server/operation-runner.js +21 -1
  53. package/dist/internal/server/person-context.d.ts +35 -0
  54. package/dist/internal/server/person-context.js +115 -0
  55. package/dist/internal/server/semantics.d.ts +1 -1
  56. package/dist/internal/surfaces.d.ts +1 -1
  57. package/dist/internal/surfaces.js +4 -4
  58. package/dist/registry.d.ts +7 -0
  59. package/dist/registry.js +4 -0
  60. package/dist/styles.css +3 -168
  61. package/package.json +13 -13
@@ -0,0 +1,69 @@
1
+ import {
2
+ DEFAULT_CREDENTIAL_LEVEL,
3
+ DEFAULT_OAUTH_CONNECTION_ID,
4
+ oauthProviderPlaceholders
5
+ } from "@ekanos/sdk/integration";
6
+ import { resolveConnectAs } from "./console-state.js";
7
+ import { oauthClientKey } from "./local-secrets.js";
8
+ const MAIN_CONNECTION_LABEL = "Main connection";
9
+ function declaredOAuthConnections(definition) {
10
+ return [
11
+ ...definition.oauth ? [
12
+ [DEFAULT_OAUTH_CONNECTION_ID, definition.oauth]
13
+ ] : [],
14
+ ...Object.entries(definition.oauthConnections ?? {})
15
+ ];
16
+ }
17
+ function connectionKeys(oauth, filled) {
18
+ const keys = /* @__PURE__ */ new Map();
19
+ const add = (name, label = name, secret = true) => {
20
+ if (!keys.has(name)) {
21
+ keys.set(name, { name, label, secret, set: filled.has(name) });
22
+ }
23
+ };
24
+ for (const field of oauth.teamApp?.fields ?? []) {
25
+ add(field.secretName, field.label, field.sensitive !== false);
26
+ }
27
+ add(oauth.credentials.clientIdSecretName);
28
+ add(oauth.credentials.clientSecretSecretName);
29
+ for (const name of oauthProviderPlaceholders(oauth.provider)) {
30
+ add(name, name, false);
31
+ }
32
+ return [...keys.values()];
33
+ }
34
+ function describeOAuthConnections(input) {
35
+ const filled = new Set(input.filled);
36
+ return declaredOAuthConnections(input.definition).map(([id, oauth]) => {
37
+ const live = id === DEFAULT_OAUTH_CONNECTION_ID ? input.held?.connection ?? null : input.held?.connections[id] ?? null;
38
+ const clientId = input.values[oauth.credentials.clientIdSecretName];
39
+ const kept = input.stored[id];
40
+ const storedValid = kept && clientId && kept.clientKey === oauthClientKey(clientId) ? kept : null;
41
+ const level = oauth.level ?? DEFAULT_CREDENTIAL_LEVEL;
42
+ const connectAs = input.personal ? resolveConnectAs({
43
+ switches: input.personal.switches,
44
+ slug: input.personal.slug,
45
+ credential: `oauth:${id}`,
46
+ level
47
+ }) : void 0;
48
+ const mine = input.personal?.stored[id];
49
+ const mineValid = mine && clientId && mine.clientKey === oauthClientKey(clientId) ? mine : null;
50
+ const obtainedAt = connectAs === "me" ? mineValid?.obtainedAt ?? null : live?.obtainedAt ?? storedValid?.obtainedAt ?? null;
51
+ return {
52
+ id,
53
+ label: id === DEFAULT_OAUTH_CONNECTION_ID ? MAIN_CONNECTION_LABEL : oauth.label ?? id,
54
+ ...oauth.description ? { description: oauth.description } : {},
55
+ teamApp: oauth.teamApp !== void 0,
56
+ keys: connectionKeys(oauth, filled),
57
+ ...oauth.provider.authorizationParams && Object.keys(oauth.provider.authorizationParams).length > 0 ? { authorizationParams: { ...oauth.provider.authorizationParams } } : {},
58
+ level,
59
+ ...connectAs ? { connectAs } : {},
60
+ connected: obtainedAt !== null,
61
+ obtainedAt
62
+ };
63
+ });
64
+ }
65
+ export {
66
+ MAIN_CONNECTION_LABEL,
67
+ declaredOAuthConnections,
68
+ describeOAuthConnections
69
+ };
@@ -1,5 +1,5 @@
1
1
  import type { IntegrationContext } from '@ekanos/sdk';
2
- import type { OAuthProviderDeclaration, OAuthTokens } from '@ekanos/sdk/integration';
2
+ import { type OAuthProviderDeclaration, type OAuthTokens } from '@ekanos/sdk/integration';
3
3
  /**
4
4
  * ─────────────────────────────────────────────────────────────────────────────
5
5
  * THE LOCALHOST OAUTH LOOP — pure helpers
@@ -1,3 +1,6 @@
1
+ import {
2
+ joinOAuthScopes
3
+ } from "@ekanos/sdk/integration";
1
4
  import { createHash, randomBytes } from "node:crypto";
2
5
  function generateCodeVerifier() {
3
6
  return randomBytes(32).toString("base64url");
@@ -40,7 +43,7 @@ function buildAuthorizeUrl(input) {
40
43
  url.searchParams.set("response_type", "code");
41
44
  url.searchParams.set("client_id", input.clientId);
42
45
  url.searchParams.set("redirect_uri", input.redirectUri);
43
- url.searchParams.set("scope", input.provider.scopes.join(" "));
46
+ url.searchParams.set("scope", joinOAuthScopes(input.provider));
44
47
  url.searchParams.set("state", input.state);
45
48
  if (input.codeChallenge) {
46
49
  url.searchParams.set("code_challenge", input.codeChallenge);
@@ -8,6 +8,19 @@ export declare function persistOauthConnection(args: {
8
8
  tokens: OAuthTokens;
9
9
  fact: LiveConnection;
10
10
  }): void;
11
+ /**
12
+ * Keep the OAuth connection the local person made as themselves, in their own
13
+ * tier. It is never replayed: `onTokens` already wrote what it writes into
14
+ * that tier, so the tier alone is the connection.
15
+ */
16
+ export declare function persistPersonOauthConnection(args: {
17
+ projectRoot: string;
18
+ slug: string;
19
+ connectionId: string;
20
+ clientId: string;
21
+ tokens: OAuthTokens;
22
+ fact: LiveConnection;
23
+ }): void;
11
24
  /** Whether tokens are stored for `slug`, whether or not a live context holds them. */
12
25
  export declare function hasStoredOauthConnection(projectRoot: string, slug: string): boolean;
13
26
  /** Replay stored tokens into a freshly built live context, once per context. */
@@ -1,9 +1,11 @@
1
1
  import {
2
2
  DEFAULT_OAUTH_CONNECTION_ID
3
3
  } from "@ekanos/sdk/integration";
4
+ import { HARNESS_USER_ID } from "../../registry.js";
4
5
  import {
5
6
  oauthClientKey,
6
7
  readOauthConnections,
8
+ updatePersonTier,
7
9
  writeOauthConnection
8
10
  } from "./local-secrets.js";
9
11
  function oauthFor(definition, connectionId) {
@@ -30,6 +32,31 @@ function persistOauthConnection(args) {
30
32
  );
31
33
  }
32
34
  }
35
+ function persistPersonOauthConnection(args) {
36
+ const written = updatePersonTier({
37
+ projectRoot: args.projectRoot,
38
+ slug: args.slug,
39
+ userId: HARNESS_USER_ID,
40
+ update: (tier) => ({
41
+ ...tier,
42
+ oauth: {
43
+ ...tier.oauth,
44
+ [args.connectionId]: {
45
+ tokens: args.tokens,
46
+ obtainedAt: args.fact.obtainedAt,
47
+ expiresAt: args.fact.expiresAt,
48
+ scope: args.fact.scope,
49
+ clientKey: oauthClientKey(args.clientId)
50
+ }
51
+ }
52
+ })
53
+ });
54
+ if (!written.ok) {
55
+ console.error(
56
+ `[harness:${args.slug}] could not keep the personal OAuth connection: ${written.message}`
57
+ );
58
+ }
59
+ }
33
60
  function hasStoredOauthConnection(projectRoot, slug) {
34
61
  return Object.keys(readOauthConnections({ projectRoot, slug })).length > 0;
35
62
  }
@@ -72,5 +99,6 @@ async function restoreOauthConnections(args) {
72
99
  export {
73
100
  hasStoredOauthConnection,
74
101
  persistOauthConnection,
102
+ persistPersonOauthConnection,
75
103
  restoreOauthConnections
76
104
  };
@@ -1,4 +1,5 @@
1
1
  import {
2
+ interpretErrorFixture,
2
3
  isConfirmed,
3
4
  requiresConfirmation
4
5
  } from "@ekanos/integration-schema";
@@ -23,6 +24,14 @@ function servesBindingMode(integration, channel) {
23
24
  }
24
25
  }
25
26
  const OP_KEY = /^(tool|action)\/([a-z][a-z0-9_-]*)$/;
27
+ class FixtureRefusal extends Error {
28
+ constructor(reason, detail) {
29
+ super(detail ?? reason);
30
+ this.name = "FixtureRefusal";
31
+ this.reason = reason;
32
+ if (detail !== void 0) this.detail = detail;
33
+ }
34
+ }
26
35
  class DeadlineError extends Error {
27
36
  constructor() {
28
37
  super("operation deadline exceeded");
@@ -199,6 +208,9 @@ async function runOperation(request, deps) {
199
208
  if (error instanceof DeadlineError) {
200
209
  return refuse("deadline_exceeded", void 0, "error");
201
210
  }
211
+ if (error instanceof FixtureRefusal) {
212
+ return refuse(error.reason, error.detail, "error");
213
+ }
202
214
  return refuse(
203
215
  "execution_failed",
204
216
  error instanceof Error ? error.message : String(error),
@@ -239,8 +251,16 @@ async function runOperation(request, deps) {
239
251
  function fixtureOutput(fixtures, integration, opKey, scenario, _contract, operation) {
240
252
  if (scenario === "error") {
241
253
  const authored2 = fixtures.read(integration, opKey, "error");
254
+ if (!authored2.found) throw new Error("error scenario");
255
+ const error = interpretErrorFixture(authored2.value);
256
+ if (error.kind === "refusal") {
257
+ throw new FixtureRefusal(error.reason, error.message);
258
+ }
259
+ if (error.kind === "invalid") {
260
+ throw new Error(`error fixture is invalid: ${error.problem}`);
261
+ }
242
262
  throw new Error(
243
- authored2.found ? `error scenario: ${typeof authored2.value === "string" ? authored2.value : JSON.stringify(redactSensitive(authored2.value))}` : "error scenario"
263
+ `error scenario: ${typeof error.value === "string" ? error.value : JSON.stringify(redactSensitive(error.value))}`
244
264
  );
245
265
  }
246
266
  const authored = fixtures.read(integration, opKey, scenario);
@@ -0,0 +1,35 @@
1
+ import type { IntegrationSecrets } from '@ekanos/sdk';
2
+ import type { MockIntegrationContext } from '@ekanos/sdk/testing';
3
+ import type { HarnessRunAs } from '../../api-types.js';
4
+ /** The local person's tier, read from and written through to disk. */
5
+ export declare function createPersonSecrets(args: {
6
+ projectRoot: string;
7
+ slug: string;
8
+ userId?: string;
9
+ }): IntegrationSecrets;
10
+ /** The live context as `runAs` calls it. Never mutates `base`. */
11
+ /**
12
+ * The context a machine call runs with — what the host gives an
13
+ * integration's declared schedules and webhooks (plan 261): a machine actor
14
+ * and principal, no `ctx.identity` ever, and `ctx.storage.user` refused.
15
+ * `ctx.secrets` stays the team tier.
16
+ */
17
+ export declare function machineContext(base: MockIntegrationContext): MockIntegrationContext;
18
+ export declare function contextAs(args: {
19
+ base: MockIntegrationContext;
20
+ runAs: HarnessRunAs;
21
+ projectRoot: string;
22
+ slug: string;
23
+ }): MockIntegrationContext;
24
+ /**
25
+ * The context `onTokens` / `onActivate` run with when a credential is being
26
+ * connected as the person: a `user` connection whose `ctx.secrets` IS the
27
+ * person's tier (over the app credentials the operator filled in) and whose
28
+ * `ctx.identity.secrets` is the same store.
29
+ */
30
+ export declare function personConnectContext(args: {
31
+ base: MockIntegrationContext;
32
+ projectRoot: string;
33
+ slug: string;
34
+ adminSecrets: Readonly<Record<string, string>>;
35
+ }): MockIntegrationContext;
@@ -0,0 +1,115 @@
1
+ import { HARNESS_USER_ID, HARNESS_USER_NAME } from "../../registry.js";
2
+ import { readPersonTier, updatePersonTier } from "./local-secrets.js";
3
+ const MACHINE_ACTOR = {
4
+ kind: "machine",
5
+ tokenId: "harness-machine",
6
+ createdBy: null
7
+ };
8
+ function createPersonSecrets(args) {
9
+ const userId = args.userId ?? HARNESS_USER_ID;
10
+ const where = { projectRoot: args.projectRoot, slug: args.slug, userId };
11
+ const values = () => {
12
+ const tier = readPersonTier(where);
13
+ return { ...tier.activation, ...tier.secrets };
14
+ };
15
+ return {
16
+ async get(name) {
17
+ return values()[name] ?? null;
18
+ },
19
+ async names() {
20
+ return Object.keys(values()).sort();
21
+ },
22
+ async set(name, value) {
23
+ const written = updatePersonTier({
24
+ ...where,
25
+ update: (tier) => ({
26
+ ...tier,
27
+ secrets: { ...tier.secrets, [name]: value }
28
+ })
29
+ });
30
+ if (!written.ok) throw new Error(written.message);
31
+ }
32
+ };
33
+ }
34
+ function hasPersonValues(args) {
35
+ const tier = readPersonTier({ ...args, userId: HARNESS_USER_ID });
36
+ return Object.keys(tier.activation).length > 0 || Object.keys(tier.secrets).length > 0;
37
+ }
38
+ const userPrincipal = {
39
+ kind: "user",
40
+ userId: HARNESS_USER_ID,
41
+ displayName: HARNESS_USER_NAME,
42
+ avatarUrl: null
43
+ };
44
+ const userActor = {
45
+ kind: "user",
46
+ userId: HARNESS_USER_ID,
47
+ role: { name: "owner", hierarchyLevel: 1 }
48
+ };
49
+ function machineUserStore() {
50
+ const refuse = () => {
51
+ throw new Error(
52
+ 'ctx.storage.user is unavailable for machine actors: there is no user to scope the row to. Switch Run as to "me" to test a person.'
53
+ );
54
+ };
55
+ return {
56
+ get: async () => refuse(),
57
+ set: async () => refuse(),
58
+ delete: async () => refuse()
59
+ };
60
+ }
61
+ function machineContext(base) {
62
+ const storage = {
63
+ ...base.storage,
64
+ user: machineUserStore()
65
+ };
66
+ return {
67
+ ...base,
68
+ userId: null,
69
+ actor: MACHINE_ACTOR,
70
+ principal: { kind: "machine" },
71
+ identity: void 0,
72
+ storage
73
+ };
74
+ }
75
+ function contextAs(args) {
76
+ const { base, runAs } = args;
77
+ if (runAs === "machine") return machineContext(base);
78
+ const identity = hasPersonValues(args) ? { userId: HARNESS_USER_ID, secrets: createPersonSecrets(args) } : void 0;
79
+ return {
80
+ ...base,
81
+ userId: HARNESS_USER_ID,
82
+ actor: userActor,
83
+ principal: userPrincipal,
84
+ identity
85
+ };
86
+ }
87
+ function personConnectContext(args) {
88
+ const own = createPersonSecrets(args);
89
+ const secrets = {
90
+ async get(name) {
91
+ return await own.get(name) ?? args.adminSecrets[name] ?? null;
92
+ },
93
+ async names() {
94
+ return [
95
+ .../* @__PURE__ */ new Set([...await own.names(), ...Object.keys(args.adminSecrets)])
96
+ ].sort();
97
+ },
98
+ set: (name, value) => own.set(name, value)
99
+ };
100
+ return {
101
+ ...args.base,
102
+ connection: { owner: "user" },
103
+ userId: HARNESS_USER_ID,
104
+ actor: userActor,
105
+ principal: userPrincipal,
106
+ identity: { userId: HARNESS_USER_ID, secrets: own },
107
+ secrets
108
+ };
109
+ }
110
+ export {
111
+ contextAs,
112
+ createPersonSecrets,
113
+ machineContext,
114
+ personConnectContext
115
+ };
@@ -14,7 +14,7 @@ export type ExecutorLimits = {
14
14
  maxOutputBytes: number;
15
15
  deadlineMs: number;
16
16
  };
17
- export declare const REFUSAL_MESSAGES: Record<"binding_missing" | "confirmation_required" | "deadline_exceeded" | "execution_failed" | "input_too_large" | "invalid_input" | "mode_not_permitted" | "operation_not_declared" | "operation_not_in_contract" | "output_invalid" | "output_too_large" | "product_unavailable" | "rate_limited" | "slot_unknown" | "write_not_approved" | "write_refused_on_channel", string>;
17
+ export declare const REFUSAL_MESSAGES: Record<"binding_missing" | "confirmation_required" | "deadline_exceeded" | "execution_failed" | "input_too_large" | "invalid_input" | "mode_not_permitted" | "not_connected" | "operation_not_declared" | "operation_not_in_contract" | "output_invalid" | "output_too_large" | "product_unavailable" | "rate_limited" | "slot_unknown" | "write_not_approved" | "write_refused_on_channel", string>;
18
18
  export type ValidationOutcome = {
19
19
  valid: true;
20
20
  } | {
@@ -19,7 +19,7 @@ export interface HarnessSurface {
19
19
  label: string;
20
20
  /** Shorter label for the landing page's link row, where space is tight. */
21
21
  shortLabel: string;
22
- /** Font Awesome spec — a weight the FREE package actually ships. */
22
+ /** Phosphor icon name (phosphoricons.com). */
23
23
  icon: string;
24
24
  }
25
25
  export declare const HARNESS_SURFACES: readonly HarnessSurface[];
@@ -3,25 +3,25 @@ const HARNESS_SURFACES = [
3
3
  segment: "widgets",
4
4
  label: "Widgets",
5
5
  shortLabel: "Widgets",
6
- icon: "fa-table-cells-large"
6
+ icon: "grid-four"
7
7
  },
8
8
  {
9
9
  segment: "tile",
10
10
  label: "Marketplace tile",
11
11
  shortLabel: "Tile",
12
- icon: "fa-store"
12
+ icon: "storefront"
13
13
  },
14
14
  {
15
15
  segment: "activation",
16
16
  label: "Activation",
17
17
  shortLabel: "Activation",
18
- icon: "fa-plug"
18
+ icon: "plug"
19
19
  },
20
20
  {
21
21
  segment: "triggers",
22
22
  label: "Triggers",
23
23
  shortLabel: "Triggers",
24
- icon: "fa-bolt"
24
+ icon: "lightning"
25
25
  }
26
26
  ];
27
27
  export {
@@ -431,6 +431,13 @@ export type DataMode = (typeof DATA_MODES)[number];
431
431
  * there is no database.
432
432
  */
433
433
  export declare const HARNESS_ACCOUNT_ID = "00000000-0000-4000-8000-000000000001";
434
+ /**
435
+ * The one local person the harness acts as when a call runs "as me"
436
+ * (plan 261 R6): `ctx.principal.userId` and the key of the per-person
437
+ * credential tier in `.ekanos/local-secrets.json`.
438
+ */
439
+ export declare const HARNESS_USER_ID = "00000000-0000-4000-8000-000000000003";
440
+ export declare const HARNESS_USER_NAME = "Local developer";
434
441
  export declare const HARNESS_SOURCE_ID = "00000000-0000-4000-8000-000000000002";
435
442
  export declare const HARNESS_ACCOUNT_SLUG = "harness-team";
436
443
  /**
package/dist/registry.js CHANGED
@@ -1,6 +1,8 @@
1
1
  const FIXTURE_VARIANTS = ["default", "empty", "error"];
2
2
  const DATA_MODES = ["fixtures", "live"];
3
3
  const HARNESS_ACCOUNT_ID = "00000000-0000-4000-8000-000000000001";
4
+ const HARNESS_USER_ID = "00000000-0000-4000-8000-000000000003";
5
+ const HARNESS_USER_NAME = "Local developer";
4
6
  const HARNESS_SOURCE_ID = "00000000-0000-4000-8000-000000000002";
5
7
  const HARNESS_ACCOUNT_SLUG = "harness-team";
6
8
  function asHarnessDefinition(definition) {
@@ -93,6 +95,8 @@ export {
93
95
  HARNESS_ACCOUNT_ID,
94
96
  HARNESS_ACCOUNT_SLUG,
95
97
  HARNESS_SOURCE_ID,
98
+ HARNESS_USER_ID,
99
+ HARNESS_USER_NAME,
96
100
  asHarnessDefinition,
97
101
  collectSeeds,
98
102
  findEgressMismatch,
package/dist/styles.css CHANGED
@@ -60,174 +60,9 @@
60
60
  --font-heading: var(--font-heading-fallback), var(--font-sans);
61
61
  }
62
62
 
63
- /* ── Font Awesome Free: missing-glyph fallback ────────────────────────────────
64
- *
65
- * The harness loads Font Awesome FREE (see the note in `RootLayout` — the
66
- * host's Pro webfonts are commercially licensed and cannot ship in a partner's
67
- * scaffold). Free has a smaller glyph set, so a Pro-only name such as
68
- * `fa-aperture` or `fa-clouds-sun` never gets a `--fa` codepoint, `content:
69
- * var(--fa)` computes to nothing, and the icon vanishes with no warning.
70
- *
71
- * `:where()` carries zero specificity, so every real `.fa-<name>{--fa:…}` rule
72
- * in the vendor CSS still wins. Only genuinely-absent glyphs fall through to
73
- * the question mark, which reads as "this glyph isn't in the free font" rather
74
- * than as a broken layout. */
75
- :where(.fa-solid, .fa-regular, .fa-light, .fa-duotone, .fa-thin, .fa) {
76
- --fa: '\f059'; /* fa-circle-question */
77
- }
78
-
79
- /* ── Font Awesome Free: hand `::before` back to the icon font ─────────────────
80
- *
81
- * `@ekanos/ui/theme.css` imports that package's `base.css`, which paints a
82
- * placeholder for a host that loads NO icon font at all:
83
- *
84
- * :where(i[class*='fa-'])::before {
85
- * content: var(--ekanos-icon-fallback, '\25a1');
86
- * font-family: ui-sans-serif, system-ui, sans-serif;
87
- * font-weight: 400;
88
- * opacity: 0.55;
89
- * }
90
- *
91
- * Its comment reasons that `:where()` at (0,0,1) loses to Font Awesome's own
92
- * `:is(…)::before` at (0,1,1), so the rule "contributes nothing" the instant a
93
- * Font Awesome stylesheet is present. That holds for `content` — the ONLY
94
- * property FA declares on the pseudo-element (`content: var(--fa)/""`). It does
95
- * NOT hold for `font-family`, `font-weight` or `opacity`: FA declares the family
96
- * and weight on the ELEMENT (`.fa-solid { font-family: var(--_fa-family);
97
- * font-weight: var(--fa-style, 900) }`), never on `::before`. So those three
98
- * declarations have no competitor at pseudo-element level and win regardless of
99
- * specificity or cascade layer — a declared value always beats an inherited one.
100
- *
101
- * Net effect with FA Free loaded: `content` is the CORRECT codepoint (verified
102
- * in-browser: U+F043 for `fa-droplet`) but it is painted in `system-ui` at
103
- * weight 400, and no system font carries a Private Use Area glyph there — so
104
- * every icon rendered as the browser's missing-glyph hex box (a rectangle of
105
- * tiny hex digits, which reads as a striped/barcode box) at 55% opacity.
106
- *
107
- * Handing the pseudo-element back to `inherit` restores FA's own family and
108
- * weight off the `<i>`, which is correct for solid, regular AND brands without
109
- * naming a family here. `:is()` at (0,1,0) beats the `:where()` it undoes, and
110
- * being unlayered it also outranks the `layer(base)` base.css is imported into.
111
- *
112
- * This lives here, not in `@ekanos/ui`, because the placeholder is correct for
113
- * the case it was written for — a host with no icon font. It is only wrong for a
114
- * host that HAS one, which is this app. */
115
- :is(
116
- .fa,
117
- .fas,
118
- .far,
119
- .fab,
120
- .fa-solid,
121
- .fa-regular,
122
- .fa-brands,
123
- .fa-classic,
124
- .fa-light,
125
- .fa-thin,
126
- .fa-duotone,
127
- .fa-sharp
128
- )::before {
129
- font-family: inherit;
130
- font-weight: inherit;
131
- opacity: 1;
132
- }
133
-
134
- /* The Pro-only FAMILY classes get no `font-family` from the Free stylesheet at
135
- * all, so an `<i class="fa-light fa-spinner">` falls back to the body font and
136
- * renders tofu even when `--fa` holds a codepoint Free ships.
137
- * `IconStyleOverrideProvider value="solid"` in `RootLayout` rewrites these
138
- * for everything under it, but it cannot reach an icon rendered outside that
139
- * subtree — and `@ekanos/ui`'s own `Spinner` hardcodes `fa-light fa-spinner`. Pin
140
- * them to the one weight Free actually ships so they degrade to the solid face
141
- * instead of vanishing. Family is spelled out because `--_fa-family` is set by
142
- * the very FA rule that does not match these classes. */
143
- i:is(.fa-light, .fa-thin, .fa-duotone, .fa-sharp) {
144
- font-family: 'Font Awesome 7 Free';
145
- font-weight: 900;
146
- }
147
-
148
- /* ── Pro glyph names → their nearest Free equivalent ──────────────────────────
149
- *
150
- * The `--fa: '\f059'` rule above is the LAST resort: it keeps an unknown glyph
151
- * legible as a question mark instead of collapsing the layout. But a wall of
152
- * question marks is its own kind of broken-looking, and several of the Pro
153
- * names our example integrations use have an obvious Free counterpart that
154
- * carries the same meaning.
155
- *
156
- * Aliasing those by codepoint here is strictly better than the question mark
157
- * and strictly honest about what it is: an APPROXIMATION for the Free build.
158
- * `fa-cloud` is not `fa-clouds` and `fa-sun` is not `fa-sun-bright` — in
159
- * production, where Ekanos loads Font Awesome Pro, the real Pro rule is (0,1,0)
160
- * and lives in an unlayered vendor sheet, so it wins over the `i.fa-*` selectors
161
- * below and the authored Pro glyph renders exactly as designed. Nothing here
162
- * changes what a correctly licensed host shows.
163
- *
164
- * Keep this list to names our own bundled examples actually reference, or a
165
- * real Pro-only name a partner build hit and reported (the block below it) —
166
- * it is a courtesy for demo/partner surfaces, not a general-purpose
167
- * Pro→Free shim covering every Pro glyph. `src/_impl/__tests__/
168
- * fa-free-icon-names.test.tsx` in `@ekanos/ui` asserts every name here is
169
- * genuinely Free-missing and every codepoint names a real Free glyph. */
170
- i.fa-sun-bright {
171
- --fa: '\f185'; /* fa-sun */
172
- }
173
- i.fa-moon-stars {
174
- --fa: '\f186'; /* fa-moon */
175
- }
176
- i.fa-cloud-fog {
177
- --fa: '\f75f'; /* fa-smog */
178
- }
179
- i.fa-cloud-drizzle {
180
- --fa: '\f73d'; /* fa-cloud-rain */
181
- }
182
- i.fa-cloud-showers {
183
- --fa: '\f740'; /* fa-cloud-showers-heavy */
184
- }
185
- i.fa-clouds {
186
- --fa: '\f0c2'; /* fa-cloud */
187
- }
188
- i.fa-clouds-sun {
189
- --fa: '\f6c4'; /* fa-cloud-sun */
190
- }
191
- i.fa-clouds-moon {
192
- --fa: '\f6c3'; /* fa-cloud-moon */
193
- }
194
- i.fa-cloud-question {
195
- --fa: '\f059'; /* fa-circle-question */
196
- }
197
- i.fa-sparkles {
198
- --fa: '\e2ca'; /* fa-wand-magic-sparkles */
199
- }
200
-
201
- /* Reported by a partner build (2026-09-08): all seven are real Font Awesome
202
- * PRO names (verified against the host's Font Awesome Pro subset) that Free does not
203
- * ship, so every one of them was rendering the bare circle-question fallback
204
- * with no indication why. `fa-circle-question` itself was also reported, but
205
- * it is NOT Free-missing — Free ships it natively at the same codepoint
206
- * (`\f059`) the fallback rule above uses, so a probe that treats "content
207
- * resolved to \f059" as "broken" cannot tell a genuine circle-question icon
208
- * apart from the fallback. That is a probe-methodology caveat, not a shim
209
- * this file can fix. */
210
- i.fa-cloud-snow {
211
- --fa: '\f2dc'; /* fa-snowflake */
212
- }
213
- i.fa-cloud-hail {
214
- --fa: '\f73b'; /* fa-cloud-meatball */
215
- }
216
- i.fa-cloud-hail-mixed {
217
- --fa: '\f73b'; /* fa-cloud-meatball */
218
- }
219
- i.fa-fog {
220
- --fa: '\f75f'; /* fa-smog */
221
- }
222
- i.fa-sun-cloud {
223
- --fa: '\f6c4'; /* fa-cloud-sun */
224
- }
225
- i.fa-moon-cloud {
226
- --fa: '\f6c3'; /* fa-cloud-moon */
227
- }
228
- i.fa-cloud-bolt-sun {
229
- --fa: '\f76c'; /* fa-cloud-bolt */
230
- }
63
+ /* Icons are Phosphor (MIT): `@ekanos/ui/theme.css` declares the fonts, which
64
+ * ship inside `@ekanos/ui`, and draws every icon. Nothing here needs to patch
65
+ * the icon font. */
231
66
 
232
67
  @layer base {
233
68
  body {