@company-semantics/contracts 37.0.0 → 38.1.0

package/src/notifications/renderers/email/render.ts

@@ -216,8 +216,10 @@ export function renderElement(
       ];
 
     case "heroImage": {
-      // Stated as attributes, not just style: they are the image's intrinsic size
-      // and every client uses them to reserve space before it loads.
+      // Stated as attributes, not just style: they are the image's intrinsic
+      // size, every client uses them to reserve space before it loads, and
+      // `./styles.ts`'s `ampify` reads them to decide whether the AMP surface can
+      // draw an `<amp-img>` at all.
       const dimensions =
         element.width !== undefined && element.height !== undefined
           ? ` width="${element.width}" height="${element.height}"`

package/src/notifications/renderers/email/shells.ts

@@ -6,9 +6,6 @@
  * composes ONE list of `EmailLine`s and both surfaces derive from it, so the two
  * can never disagree about what the email says.
  *
- * There was a third shell — `ampShell` — retired in ADR-CONTRACTS-091. See
- * `./index.ts`: the AMP part cost Gmail readers their dark mode.
- *
  * INVARIANTS:
  * - Pure functions of their input lines. No clock, no environment, no I/O.
  * - These strings are the email's actual markup, and
@@ -16,10 +13,16 @@
  *   character-for-character.
  */
 
-import { BASE_STYLE, DARK_STYLE } from "./colors";
+import { BASE_STYLE, DARK_STYLE, hoverStyle } from "./colors";
 import type { Spacing } from "./constants";
 import { MSO_CTA_STYLE } from "./cta";
-import { inlineOf, inlineStyles } from "./styles";
+import {
+  AMP_RECIPE_RULES,
+  ampify,
+  inlineOf,
+  inlineStyles,
+  styleClass,
+} from "./styles";
 
 /**
  * One rendered line — both presentations of one thing the notification says,
@@ -45,16 +48,18 @@ export interface EmailLine {
  * protecting our colours, apply its dark background, and leave the inline LIGHT
  * text colour sitting on top of it. The two ship together or not at all.
  *
- * Only Apple Mail, iOS Mail and Outlook for Mac read any of this. No Gmail client
- * honours `prefers-color-scheme` on any surface; what Gmail iOS does instead is
- * invert this part post-delivery, which nothing here can stop — and which is why
- * the body still states an explicit background rather than trusting a default.
- * That inversion is not a fallback we tolerate, it is the ONLY dark mode a Gmail
- * iOS reader gets, and preserving it is why the AMP surface was retired
- * (ADR-CONTRACTS-091): Gmail leaves an AMP part alone, so having one would have
- * turned this inversion off. Measured in
- * `company-semantics-backend/docs/dark-mode-probe.md` — Gmail web, by contrast,
- * recolours nothing at all.
+ * Only Apple Mail, iOS Mail and Outlook for Mac read any of this. Clients that
+ * recolour instead (Outlook.com, Windows Outlook, and — measured —
+ * **Gmail iOS**) ignore both metas and rewrite the inline styles post-delivery.
+ * Nothing here can stop that, which is why the body still states an explicit
+ * background rather than trusting a default.
+ *
+ * Do not read that as a degradation to fix: Gmail iOS's inversion of THIS part is
+ * the only dark mode a Gmail iOS reader gets, and preserving it is why `ampShell`'s
+ * output is never sent (ADR-CONTRACTS-092). Gmail web, by contrast, recolours
+ * nothing at all — a light email stays light in a dark client, and no surface fixes
+ * that. Gmail Android is untested: unknown, not negative.
+ * `company-semantics-backend/docs/dark-mode-probe.md`.
  *
  * The `<!--[if mso]>` block is the mirror image: it is read ONLY by the Outlook
  * Word engine, and undoes the one layout that engine cannot render — a linked
@@ -87,6 +92,87 @@ ${inner}
 </html>`;
 }
 
+/**
+ * Wrap rendered lines in the AMP4EMAIL shell (ADR-CONTRACTS-089, -091, -092).
+ *
+ * ⚠️ **THIS BODY IS NEVER SENT, AND MUST NOT BE.** It is rendered, previewed in the
+ * Ladle gallery, and dropped. Delivering it is a REGRESSION, not a feature — see
+ * below. `company-semantics-backend`'s `EmailDelivery.test.ts` fails if it ever
+ * reaches the transport, and that test is the invariant; this comment is only its
+ * explanation.
+ *
+ * **Why it is not sent.** Gmail iOS inverts the `text/html` part post-delivery and
+ * does **NOT** touch a `text/x-amp-html` part. That inversion is the ONLY dark mode
+ * a Gmail iOS reader gets — no Gmail client honours `prefers-color-scheme` on any
+ * surface — so shipping an AMP part would switch it off and hand them a white email
+ * in a dark client. This surface buys `:hover` in Gmail and would cost dark mode in
+ * Gmail. That trade was measured and refused (ADR-CONTRACTS-091), and the measurement
+ * is `company-semantics-backend/docs/dark-mode-probe.md`. ADR-CONTRACTS-089 asserted
+ * the opposite — "AMP clients force-invert, so they never got our dark colours
+ * anyway" — and that is FALSE: Gmail web recolours nothing, Yahoo does not invert,
+ * and Gmail iOS exempts AMP.
+ *
+ * **Why it exists at all, then.** AMP is the only email format with a real animation
+ * model — `amp-animation`, `amp-bind`, `amp-position-observer` — and no arbitrary JS
+ * needed. Nothing else can make the kaomoji companions blink once, three seconds
+ * after open. That is a future worth keeping the surface alive for, and rebuilding it
+ * later costs more than carrying it inert now (ADR-CONTRACTS-092). If Google ever
+ * allows `prefers-color-scheme` here, or Gmail starts inverting AMP too, the trade
+ * flips and this is ready.
+ *
+ * **Light-only, permanently.** AMP4EMAIL disallows the `prefers-color-scheme` media
+ * feature — a hard validator error, checked with and without `data-css-strict` — so
+ * `DARK_STYLE` cannot appear here in any form. The `media` ATTRIBUTE on an AMP
+ * element takes the same feature and PASSES the validator; Gmail's runtime ignores
+ * it. Both doors are closed. That is not a gap to close; it is the format.
+ *
+ * Everything AMP forbids is absent BY CONSTRUCTION rather than by stripping:
+ *
+ * - **No inline `style`.** The lines are class-only; only `htmlShell` inlines them.
+ * - **No `!important`.** `hoverStyle(false)` — there is no inline style to beat
+ *   here, so nothing needs to win a specificity fight, and AMP forbids the keyword
+ *   anyway.
+ * - **No `<!--[if mso]>`.** `MSO_CTA_STYLE` lives in `htmlShell`'s `<head>`, never
+ *   in a line, so nothing has to remove it. Outlook is not an AMP client, and
+ *   `display: block` needs no correction in the three that are.
+ *
+ * The boilerplate hides the body until the runtime unhides it — which is why an
+ * AMP document that cannot run scripts shows nothing at all, rather than showing
+ * an unstyled version of itself.
+ */
+export function ampShell(lines: EmailLine[]): string {
+  const inner = ampify(
+    lines
+      .map((line) => line.html)
+      .filter(Boolean)
+      .join("\n"),
+  );
+  // `amp4email` rather than the `⚡4email` the spec also allows: both are valid,
+  // and one of them survives every editor, terminal and diff it will ever cross.
+  //
+  // `data-css-strict` opts into AMP's strict CSS validation. The validator warns
+  // when it is absent and says it "may become an error in the future"; our CSS
+  // passes with and without it, so taking it now costs nothing and means that
+  // future arrives already handled.
+  //
+  // The shell wears its own recipes as CLASSES, where `htmlShell` inlines them —
+  // that asymmetry is the whole surface split, and it means `body` and `frame`
+  // need no special case: `AMP_RECIPE_RULES` already states every recipe's rule.
+  return `<!DOCTYPE html>
+<html amp4email data-css-strict lang="en">
+<head><meta charset="utf-8">
+<script async src="https://cdn.ampproject.org/v0.js"></script>
+<style amp4email-boilerplate>body{visibility:hidden}</style>
+<style amp-custom>${AMP_RECIPE_RULES}
+${hoverStyle(false)}</style></head>
+<body ${styleClass("body")}>
+<div ${styleClass("frame")}>
+${inner}
+</div>
+</body>
+</html>`;
+}
+
 /**
  * Join rendered lines into the plain-text email — separated per each line's
  * spacing, with a trailing newline.

package/src/notifications/renderers/email/styles.ts

@@ -250,16 +250,10 @@ export const STYLE_NAMES = Object.keys(RECIPES) as StyleName[];
  *
  * This is the whole mechanism. A `cs-` role class is a HOOK: `darkStyle` needs it
  * in the shipped markup, so it survives. A `csr-` recipe class is a BUNDLE OF
- * DECLARATIONS: the html surface spends it and drops it. One prefix test separates
- * them — for `inlineStyles` below, and for `__tests__/colors.test.ts`, which asserts
- * every SHIPPED class has a dark rule and would otherwise trip over every recipe
- * class in this file.
- *
- * The registry once had a second consumer — the AMP surface kept these classes and
- * stated their rules, and that opposition (html inlines, AMP does not) is why it
- * exists. AMP is gone (ADR-CONTRACTS-091) and the registry stays: it is now the
- * single source for a recipe, spent in one place, and the markup it produces is
- * byte-identical either way.
+ * DECLARATIONS: the html surface spends it and drops it, the AMP surface keeps it
+ * and states its rule. One prefix test separates them — for `inlineStyles` below,
+ * and for `__tests__/colors.test.ts`, which asserts every SHIPPED class has a dark
+ * rule and would otherwise trip over every recipe class in this file.
  */
 const RECIPE_PREFIX = "csr-";
 
@@ -285,6 +279,11 @@ export function inlineOf(name: StyleName): string {
   return `${RECIPES[name].join("; ")};`;
 }
 
+/** `.csr-bubble-user { border-radius: 8px; … }` — one recipe, as a rule. */
+export function ruleOf(name: StyleName): string {
+  return `.${recipeClass(name)} { ${inlineOf(name)} }`;
+}
+
 /**
  * Class-only markup → the html surface's markup.
  *
@@ -317,3 +316,46 @@ export function inlineStyles(html: string): string {
       .join(" ");
   });
 }
+
+/**
+ * Class-only markup → the AMP surface's markup.
+ *
+ * The mirror of `inlineStyles`, and the reason both exist: that one resolves the
+ * surfaces' disagreement about STYLE, this one their disagreement about TAGS. AMP
+ * keeps the classes (its stylesheet is what needs them), so all this has to do is
+ * the one structural swap the surfaces cannot share.
+ *
+ * `<img>` → `<amp-img>`, which AMP requires and which needs explicit dimensions to
+ * reserve layout before the image loads. `../../content.ts` makes them optional,
+ * because a channel that can measure an image should not be told — so when they
+ * are absent this surface CANNOT draw the image, and says the `alt` text instead.
+ * That is a degradation, not a lie: `alt` is required exactly so a channel with
+ * nothing else has something to say, and the html surface still draws the picture.
+ *
+ * This does not contradict `supports("heroImage") === true` — `../../renderer.ts`
+ * puts `supports` on the RENDERER, and AMP is one of the email renderer's surfaces,
+ * not a renderer. Email can depict a hero image. One of its three MIME parts is
+ * plain text, which cannot, and that has never made the claim false.
+ */
+export function ampify(html: string): string {
+  return html.replace(/<img ([^>]*)>/g, (_match, attrs: string) => {
+    const sized = /\bwidth="\d+"/.test(attrs) && /\bheight="\d+"/.test(attrs);
+    if (sized) return `<amp-img ${attrs} layout="intrinsic"></amp-img>`;
+    const alt = /\balt="([^"]*)"/.exec(attrs)?.[1] ?? "";
+    // Carry the image's own spacing over to the paragraph replacing it, so the
+    // gap below it does not change with the fallback.
+    const spacing = /\bcsr-hero-(\w+)\b/.exec(attrs)?.[1] ?? "normal";
+    return `<p class="${RECIPE_PREFIX}p-${spacing}">${alt}</p>`;
+  });
+}
+
+/**
+ * Every recipe as a rule, for `<style amp-custom>`.
+ *
+ * ALL of them, always — not just the ones this email happens to use. Emitting the
+ * used subset would make the stylesheet a function of the content, so two emails
+ * would carry two different stylesheets and the snapshot would stop being a
+ * statement about the channel. ~40 rules is about 4KB against AMP's 75,000-byte
+ * budget, which `__tests__/amp.test.ts` holds us to.
+ */
+export const AMP_RECIPE_RULES = STYLE_NAMES.map(ruleOf).join("\n");

package/src/permissions/share-api.ts

@@ -8,6 +8,17 @@
  *
  * Authority: ADR-CTRL-085 (Rights Table), ADR-CTRL-086 (most-permissive
  * aggregation), ADR-BE-181 (AUTH-006 compose model).
+ *
+ * DECODER RING — the label/identifier map, stated once.
+ *
+ *   UI "General access"  = wire `visibility` / EntityVisibility
+ *                          (access scope: WHO may read)
+ *   UI "Discoverability" = wire `discoverability` / EntityDiscoverability
+ *                          (WHO knows it exists)
+ *
+ * They are SIBLINGS, not modifiers. A doc can be readable by two named people
+ * and still be globally hidden: access changes without discoverability
+ * changing (ADR-CONTRACTS-093).
  */
 import { z } from "zod";
 import { AccessLevelSchema } from "./access-levels";
@@ -41,6 +52,9 @@ export type GrantableAccessLevel = z.infer<typeof GrantableAccessLevelSchema>;
 export const EntityVisibilitySchema = z.enum(["private", "unit", "org"]);
 export type EntityVisibility = z.infer<typeof EntityVisibilitySchema>;
 
+export const EntityDiscoverabilitySchema = z.enum(["org", "owners"]);
+export type EntityDiscoverability = z.infer<typeof EntityDiscoverabilitySchema>;
+
 export const AclGrantRequestSchema = z.object({
   access_level: GrantableAccessLevelSchema,
   /**
@@ -83,7 +97,10 @@ export const AclListResponseSchema = z.object({
   owner_user_ids: z
     .array(z.string().uuid())
     .refine(uniqueValues, { message: "duplicate id in owner_user_ids" }),
-  /** General-access scope: WHO is eligible (the discoverability axis). */
+  /**
+   * General-access scope: WHO may read. NOT discoverability — see
+   * `discoverability`.
+   */
   visibility: EntityVisibilitySchema,
   /**
    * The ROLE the general-access scope grants its audience: WHAT they may do (the
@@ -92,6 +109,20 @@ export const AclListResponseSchema = z.object({
    * ignored when `visibility` is `private` (no general grant).
    */
   general_access_role: GrantableAccessLevelSchema.default("viewer"),
+  /**
+   * Who knows this entity EXISTS — a SIBLING of `visibility`, not a modifier
+   * on it (ADR-CONTRACTS-093).
+   *
+   * ABSENT => this entity type has no discoverability axis (work_item,
+   * meeting_recording). Deliberately not defaulted: `org|owners` has no honest
+   * cross-entity value, unlike `general_access_role`'s `viewer`.
+   *
+   * The policy's domain is NON-READERS only. When `visibility` is `org` every
+   * member is a reader, so the stored value affects no one — it is not erased,
+   * it simply has no subjects (ADR-CTRL-194 invariant 4). A UI therefore
+   * disables the control rather than rewriting the value.
+   */
+  discoverability: EntityDiscoverabilitySchema.optional(),
   editors_can_share: z.boolean(),
   grants: z.array(AclGrantResponseSchema),
 });
@@ -106,6 +137,14 @@ export const VisibilityPatchRequestSchema = z.object({
    * set); ignored when `tier` is `private`.
    */
   role: GrantableAccessLevelSchema.optional(),
+  /**
+   * New discoverability. OMITTED => preserve the stored value.
+   *
+   * NOTE the asymmetry with the response field: there `undefined` means "not
+   * applicable to this entity type"; here it means "leave unchanged"
+   * (ADR-CONTRACTS-093).
+   */
+  discoverability: EntityDiscoverabilitySchema.optional(),
 });
 export type VisibilityPatchRequest = z.infer<
   typeof VisibilityPatchRequestSchema