@astryxdesign/core 0.6.3-canary.e9b8aa1 → 0.6.3-canary.ea2f048

package/dist/Timer/Timer.d.ts

@@ -0,0 +1,49 @@
+import type { BaseProps } from '../BaseProps';
+import type { TextColor, TextSize, TextType, TextWeight } from '../theme/types';
+export type TimerFormat = 'elapsed' | 'clock';
+export interface TimerProps extends Omit<BaseProps<HTMLTimeElement>, 'dateTime'> {
+    /** Ref forwarded to the rendered `<time>` element. */
+    ref?: React.Ref<HTMLTimeElement>;
+    /**
+     * Unix time in milliseconds when the measured operation began. Omit it to
+     * start counting from this Timer's mount.
+     */
+    startTime?: number;
+    /**
+     * Standard duration representation.
+     * @default 'elapsed'
+     */
+    format?: TimerFormat;
+    /**
+     * Semantic text type. Matches Timestamp typography behavior.
+     * @default 'supporting'
+     */
+    type?: TextType;
+    /** Explicit font size override. Overrides the size from `type`. */
+    size?: TextSize;
+    /**
+     * Text color.
+     * @default 'secondary'
+     */
+    color?: TextColor;
+    /** Font weight override. */
+    weight?: TextWeight;
+}
+/**
+ * Displays a standardized elapsed duration without scheduling React tick renders.
+ *
+ * Timer writes changing text and its ISO 8601 duration directly to the owned
+ * `<time>` node. Use `elapsed` for compact duration text or `clock` for a
+ * stopwatch-like reading.
+ *
+ * @example
+ * ```
+ * <Timer />
+ * <Timer format="clock" />
+ * ```
+ */
+export declare function Timer({ startTime, format, type, size, color, weight, ref, xstyle, className, style, ...rest }: TimerProps): import("react").JSX.Element;
+export declare namespace Timer {
+    var displayName: string;
+}
+//# sourceMappingURL=Timer.d.ts.map

package/dist/Timer/Timer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Timer.d.ts","sourceRoot":"","sources":["../../src/Timer/Timer.tsx"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAG5C,OAAO,KAAK,EAAC,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAC,MAAM,gBAAgB,CAAC;AAsB9E,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;AA8E9C,MAAM,WAAW,UAAW,SAAQ,IAAI,CACtC,SAAS,CAAC,eAAe,CAAC,EAC1B,UAAU,CACX;IACC,sDAAsD;IACtD,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IACjC;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;OAGG;IACH,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,mEAAmE;IACnE,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,4BAA4B;IAC5B,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,KAAK,CAAC,EACpB,SAAS,EACT,MAAkB,EAClB,IAAmB,EACnB,IAAI,EACJ,KAAmB,EACnB,MAAM,EACN,GAAG,EACH,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,IAAI,EACR,EAAE,UAAU,+BA0EZ;yBAtFe,KAAK"}

package/dist/Timer/Timer.js

@@ -0,0 +1,158 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file Timer.tsx
+ * @input Uses an optional start time, standardized format, Timestamp typography, BaseProps, and React ref
+ * @output Exports Timer, TimerProps, and TimerFormat with non-rendering elapsed-time updates
+ * @position Core content primitive for elapsed duration in active operations
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Timer/Timer.spec.md
+ * - /packages/core/src/Timer/Timer.doc.mjs
+ * - /packages/core/src/Timer/Timer.test.tsx
+ * - /packages/core/src/Timer/index.ts
+ * - /apps/storybook/stories/Timer.stories.tsx
+ * - /packages/cli/assets/templates/blocks/components/Timer/
+ */
+import { useEffect, useRef, useState } from 'react';
+import * as stylex from '@stylexjs/stylex';
+import { useMergedRefs } from "../hooks/useMergedRefs.js";
+import { Text } from "../Text/index.js";
+import { mergeProps } from "../utils/index.js";
+import { themeProps } from "../utils/themeProps.js";
+import { jsx as _jsx } from "react/jsx-runtime";
+const ONE_SECOND_MS = 1000;
+const ONE_MINUTE_MS = 60 * ONE_SECOND_MS;
+const ONE_HOUR_SECONDS = 60 * 60;
+const MAX_TIMEOUT_MS = 2_147_483_647;
+function pad(value) {
+  return String(value).padStart(2, '0');
+}
+function resolveFormat(format) {
+  return format === 'clock' ? 'clock' : 'elapsed';
+}
+function getElapsedMilliseconds(now, startTime) {
+  return Math.max(0, now - startTime);
+}
+function getPresentation(elapsedMilliseconds, format) {
+  const elapsedSeconds = Math.floor(elapsedMilliseconds / ONE_SECOND_MS);
+  if (format === 'clock') {
+    const hours = Math.floor(elapsedSeconds / ONE_HOUR_SECONDS);
+    const minutes = Math.floor(elapsedSeconds % ONE_HOUR_SECONDS / 60);
+    const seconds = elapsedSeconds % 60;
+    return {
+      dateTime: `PT${elapsedSeconds}S`,
+      text: hours > 0 ? `${String(hours)}:${pad(minutes)}:${pad(seconds)}` : `${String(minutes)}:${pad(seconds)}`
+    };
+  }
+  if (elapsedSeconds < 60) {
+    return {
+      dateTime: `PT${elapsedSeconds}S`,
+      text: `${String(elapsedSeconds)}s`
+    };
+  }
+  const totalMinutes = Math.floor(elapsedSeconds / 60);
+  if (totalMinutes < 60) {
+    return {
+      dateTime: `PT${elapsedSeconds}S`,
+      text: `${String(totalMinutes)}m ${pad(elapsedSeconds % 60)}s`
+    };
+  }
+  const representedSeconds = totalMinutes * 60;
+  return {
+    dateTime: `PT${representedSeconds}S`,
+    text: `${String(Math.floor(totalMinutes / 60))}h ${pad(totalMinutes % 60)}m`
+  };
+}
+function getMillisecondsUntilNextChange(now, startTime, elapsedMilliseconds, format) {
+  if (now < startTime) {
+    return Math.min(startTime - now + ONE_SECOND_MS, MAX_TIMEOUT_MS);
+  }
+  const precision = format === 'elapsed' && elapsedMilliseconds >= ONE_HOUR_SECONDS * ONE_SECOND_MS ? ONE_MINUTE_MS : ONE_SECOND_MS;
+  return precision - elapsedMilliseconds % precision;
+}
+/**
+ * Displays a standardized elapsed duration without scheduling React tick renders.
+ *
+ * Timer writes changing text and its ISO 8601 duration directly to the owned
+ * `<time>` node. Use `elapsed` for compact duration text or `clock` for a
+ * stopwatch-like reading.
+ *
+ * @example
+ * ```
+ * <Timer />
+ * <Timer format="clock" />
+ * ```
+ */
+export function Timer({
+  startTime,
+  format = 'elapsed',
+  type = 'supporting',
+  size,
+  color = 'secondary',
+  weight,
+  ref,
+  xstyle,
+  className,
+  style,
+  ...rest
+}) {
+  const [mountTime] = useState(() => Date.now());
+  const timerRef = useRef(null);
+  const mergedRef = useMergedRefs(ref, timerRef);
+  const resolvedFormat = resolveFormat(format);
+  const initialPresentation = getPresentation(0, resolvedFormat);
+  useEffect(() => {
+    const resolvedStartTime = startTime !== undefined && Number.isFinite(startTime) ? startTime : mountTime;
+    let timeoutID;
+    let previousDateTime;
+    let previousText;
+    const tick = () => {
+      const now = Date.now();
+      const elapsedMilliseconds = getElapsedMilliseconds(now, resolvedStartTime);
+      const presentation = getPresentation(elapsedMilliseconds, resolvedFormat);
+      const node = timerRef.current;
+      if (node != null) {
+        if (presentation.text !== previousText) {
+          node.textContent = presentation.text;
+          previousText = presentation.text;
+        }
+        if (presentation.dateTime !== previousDateTime) {
+          node.dateTime = presentation.dateTime;
+          previousDateTime = presentation.dateTime;
+        }
+      }
+      timeoutID = setTimeout(tick, getMillisecondsUntilNextChange(now, resolvedStartTime, elapsedMilliseconds, resolvedFormat));
+    };
+    tick();
+    return () => {
+      if (timeoutID !== undefined) {
+        clearTimeout(timeoutID);
+      }
+    };
+  }, [mountTime, resolvedFormat, startTime]);
+  const timerProps = mergeProps(themeProps('timer'), {
+    className,
+    style
+  });
+  return /*#__PURE__*/_jsx(Text, {
+    type: type,
+    size: size,
+    color: color,
+    weight: weight,
+    xstyle: xstyle,
+    ...timerProps,
+    children: /*#__PURE__*/_jsx("time", {
+      ...rest,
+      ref: mergedRef,
+      dateTime: "PT0S",
+      ...{
+        className: "x1heor9g xt0psk2 xjb2p0i x1qlqyl8 x1j61x8r xss6m8b x1pd3egz x15bjb6t"
+      },
+      children: initialPresentation.text
+    })
+  });
+}
+Timer.displayName = 'Timer';

package/dist/Timer/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @file index.ts
+ * @input Imports Timer, TimerProps, and TimerFormat
+ * @output Public Timer component barrel
+ * @position Component subpath entry point for @astryxdesign/core/Timer
+ */
+export { Timer } from './Timer';
+export type { TimerFormat, TimerProps } from './Timer';
+//# sourceMappingURL=index.d.ts.map

package/dist/Timer/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Timer/index.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH,OAAO,EAAC,KAAK,EAAC,MAAM,SAAS,CAAC;AAC9B,YAAY,EAAC,WAAW,EAAE,UAAU,EAAC,MAAM,SAAS,CAAC"}

package/dist/Timer/index.js

@@ -0,0 +1,10 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file index.ts
+ * @input Imports Timer, TimerProps, and TimerFormat
+ * @output Public Timer component barrel
+ * @position Component subpath entry point for @astryxdesign/core/Timer
+ */
+
+export { Timer } from "./Timer.js";

package/dist/index.d.ts

@@ -107,6 +107,7 @@ export * from './Skeleton';
 export * from './StatusDot';
 export * from './Spinner';
 export * from './Timestamp';
+export * from './Timer';
 export * from './Overlay';
 export * from './Outline';
 export * from './OverflowList';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -133,6 +133,9 @@ export * from "./Spinner/index.js";
 // Timestamp display
 export * from "./Timestamp/index.js";
 
+// Elapsed timer display
+export * from "./Timer/index.js";
+
 // Overlay
 export * from "./Overlay/index.js";
 export * from "./Outline/index.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.6.3-canary.e9b8aa1",
+  "version": "0.6.3-canary.ea2f048",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -539,6 +539,11 @@
       "types": "./dist/TimeInput/index.d.ts",
       "default": "./dist/TimeInput/index.js"
     },
+    "./Timer": {
+      "source": "./src/Timer/index.ts",
+      "types": "./dist/Timer/index.d.ts",
+      "default": "./dist/Timer/index.js"
+    },
     "./Timestamp": {
       "source": "./src/Timestamp/index.ts",
       "types": "./dist/Timestamp/index.d.ts",
@@ -687,8 +692,8 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
-    "@astryxdesign/a11y-spec": "0.6.3-canary.e9b8aa1",
-    "@astryxdesign/cli": "0.6.3-canary.e9b8aa1",
+    "@astryxdesign/a11y-spec": "0.6.3-canary.ea2f048",
+    "@astryxdesign/cli": "0.6.3-canary.ea2f048",
     "@babel/cli": "^7.29.7",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^7.29.7",

package/src/Timer/Timer.doc.mjs

@@ -0,0 +1,183 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+  {
+    name: 'Elapsed time',
+    required: true,
+    description:
+      'Semantic time element containing a standardized elapsed duration.',
+  },
+];
+
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
+export const docs = {
+  name: 'Timer',
+  displayName: 'Timer',
+  category: 'Content',
+  keywords: [
+    'timer',
+    'elapsed',
+    'duration',
+    'seconds',
+    'minutes',
+    'hours',
+    'stopwatch',
+    'waiting',
+    'loading',
+    'processing',
+  ],
+  props: [
+    {
+      name: 'startTime',
+      type: 'number',
+      description:
+        "Unix time in milliseconds when the measured operation began. Omit it to start from this Timer's mount.",
+    },
+    {
+      name: 'format',
+      type: "'elapsed' | 'clock'",
+      description:
+        'Standard duration representation. Elapsed uses compact units and drops seconds after one hour; clock uses m:ss or h:mm:ss.',
+      default: "'elapsed'",
+    },
+    {
+      name: 'type',
+      type: "'body' | 'large' | 'label' | 'supporting' | 'code' | 'display-1' | 'display-2' | 'display-3' | 'inherit'",
+      description:
+        'Semantic text type. Uses the same typography behavior as Timestamp.',
+      default: "'supporting'",
+    },
+    {
+      name: 'size',
+      type: "'4xs' | '3xs' | '2xs' | 'xsm' | 'sm' | 'base' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl'",
+      description: 'Explicit font size override. Overrides the size from type.',
+    },
+    {
+      name: 'color',
+      type: "'primary' | 'secondary' | 'disabled' | 'placeholder' | 'accent' | 'inherit'",
+      description: 'Text color.',
+      default: "'secondary'",
+    },
+    {
+      name: 'weight',
+      type: "'normal' | 'medium' | 'semibold' | 'bold'",
+      description: 'Font weight override.',
+    },
+    {
+      name: 'xstyle',
+      type: 'StyleXStyles',
+      description:
+        'StyleX styles for the Text wrapper. Must be a stylex.create() value.',
+    },
+    {
+      name: 'className',
+      type: 'string',
+      description:
+        'CSS class name for the Text wrapper. Prefer xstyle for styling.',
+    },
+    {
+      name: 'style',
+      type: 'CSSProperties',
+      description:
+        'Inline styles for the Text wrapper. Prefer xstyle for styling.',
+    },
+  ],
+  examples: [
+    {
+      label: 'Elapsed duration',
+      code: '<Timer />',
+    },
+    {
+      label: 'Stopwatch clock',
+      code: '<Timer format="clock" />',
+    },
+    {
+      label: 'Operation that started before mount',
+      code: '<Timer startTime={operationStartedAt} />',
+    },
+    {
+      label: 'Match surrounding text',
+      code: `<Text>
+  Processing for <Timer type="inherit" color="inherit" />
+</Text>`,
+    },
+    {
+      label: 'Prominent elapsed time',
+      code: '<Timer type="body" size="lg" color="primary" weight="semibold" />',
+    },
+  ],
+  theming: {
+    targets: [{className: 'astryx-timer'}],
+  },
+  usage: {
+    anatomy,
+    description:
+      'Displays a standardized elapsed duration for active work without scheduling a React render on every tick. Elapsed format updates by second below one hour and by minute after one hour; clock format remains second-precise.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Use elapsed for compact duration text that may span seconds, minutes, or hours.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use clock for stopwatch-like surfaces where seconds remain meaningful after an hour.',
+      },
+      {
+        guidance: true,
+        description:
+          'Pass startTime when the operation began before Timer mounted so the display reflects the complete wait.',
+      },
+      {
+        guidance: false,
+        description:
+          'Do not use Timer for dates, time zones, or relative calendar language; use Timestamp instead.',
+      },
+      {
+        guidance: false,
+        description:
+          'Do not add aria-live unless hearing an announcement every tick is appropriate for the specific task.',
+      },
+    ],
+  },
+};
+
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
+export const docsDense = {
+  description:
+    'Standardized elapsed or stopwatch duration with clock-derived, non-rendering DOM updates.',
+  propDescriptions: {
+    startTime:
+      "operation start as Unix milliseconds; omit to count from Timer's mount",
+    format: 'elapsed compact units or clock stopwatch notation',
+    type: 'semantic text type; defaults to supporting like Timestamp',
+    size: 'explicit font size override',
+    color: 'text color; defaults to secondary like Timestamp',
+    weight: 'font weight override',
+    xstyle: 'StyleX styles for the Text wrapper',
+    className: 'CSS class for the Text wrapper',
+    style: 'inline styles for the Text wrapper',
+  },
+  usage: {
+    anatomy,
+    description:
+      'Use for active-operation elapsed time when periodic React renders would add avoidable work.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Use elapsed for compact durations and clock for stopwatch UI.',
+      },
+      {
+        guidance: true,
+        description: 'Pass startTime for work that began before mount.',
+      },
+      {
+        guidance: false,
+        description: 'Use Timestamp for dates and relative calendar language.',
+      },
+    ],
+  },
+};

package/src/Timer/Timer.spec.md

@@ -0,0 +1,215 @@
+---
+schema_version: 3
+template_version: 5
+kind: component
+id: component:Timer
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-09-22
+owners: [cixzhang]
+review_triggers: [public-api, behavior, theming, accessibility, react-runtime]
+verified_by:
+  [
+    packages/core/src/Timer/Timer.test.tsx,
+    packages/core/src/theme/themingTargets.test.ts,
+    scripts/check-knowledge.mjs,
+  ]
+modules: []
+families: []
+design_specs: []
+architecture:
+  [
+    architecture:public-component-api,
+    architecture:component-theming-surface,
+    architecture:react-component-runtime,
+  ]
+contributing: []
+system_specs:
+  [
+    spec:AST-002/DEC-1,
+    spec:AST-037/DEC-1,
+    spec:AST-037/DEC-2,
+    spec:AST-037/DEC-3,
+  ]
+---
+
+# Timer component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                                                                                                      |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | `Timer`, `TimerProps`, `TimerFormat`, optional `startTime` Unix milliseconds, `elapsed` or `clock` format, Timestamp-equivalent `type`, `size`, `color`, and `weight`, `<time>` ref, and `BaseProps<HTMLTimeElement>`.                                                        |
+| Behavior                | One semantic duration uses a standardized seconds-to-hours ladder and updates its owned DOM node without React tick renders; elapsed output drops to minute cadence after one hour.                                                                                           |
+| End-user impact         | People watching active work see a stable, consistent duration without unnecessary timer work competing with the surrounding interface.                                                                                                                                        |
+| Builder impact          | Zero-config starts on mount with Timestamp's supporting typography; callers choose only an earlier origin, standard format, or standard typography override.                                                                                                                  |
+| Compatibility/readiness | Additive first release implementing current `spec:AST-037`; no existing API or behavior changes.                                                                                                                                                                              |
+| Review checks           | Reject custom formatters/cadence, state-driven ticks, callback-count drift, post-hour elapsed second wakes, typography divergence from Timestamp, leaked resources, negative output, lost passthrough/ref behavior, unsolicited live announcements, or extra anatomy/targets. |
+| Governing rules         | `spec:AST-037`; `architecture:public-component-api`; `architecture:react-component-runtime`; `architecture:component-theming-surface`.                                                                                                                                        |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+Timer is the stable Core projection of `spec:AST-037`. It presents a standardized
+elapsed duration for active work while keeping clock ticks outside React's render
+lifecycle. Its typography surface and defaults match Timestamp so the two temporal
+content components behave consistently.
+
+## Compatibility and migration
+
+- Released default preserved: `not yet released`
+- Compatibility class: additive component and type exports
+- Controlled/uncontrolled behavior: not applicable
+- Migration decision: `spec:AST-037/DEC-1`, `spec:AST-037/DEC-2`, and
+  `spec:AST-037/DEC-3`
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- Elapsed calculation from mount or a finite caller origin.
+- The `elapsed` and `clock` representation ladders and their visible precision.
+- One `<time>` element, its visible value, synchronized ISO duration, and timer
+  resource lifecycle.
+- Avoiding React update commits for clock ticks.
+- Timestamp-equivalent `type`, `size`, `color`, and `weight` behavior.
+- The `timer` theming target on the Text wrapper.
+
+**Does not own / non-goals**
+
+- Loading indicators, waiting copy, status, or visibility — product composition.
+- Dates, relative calendar language, time zones, or absolute instants — Timestamp.
+- Pause, resume, countdown, deadlines, alarms, laps, sub-second precision, custom
+  formatters, or caller-controlled scheduling cadence.
+- Automatic live-region announcements.
+
+Countdown is deferred to a later contract. The standard formatting and scheduling
+helpers remain direction-independent so that extension does not require replacing
+the current format API.
+
+## Public concepts
+
+| Concept         | Closed values or states                   | Meaning                                              | Availability | Default                                                                        | Owner             | Stability | Invalid-value behavior                                     |
+| --------------- | ----------------------------------------- | ---------------------------------------------------- | ------------ | ------------------------------------------------------------------------------ | ----------------- | --------- | ---------------------------------------------------------- |
+| Elapsed origin  | Mount time or finite `startTime`          | Unix-millisecond origin for elapsed duration         | Always       | Mount time                                                                     | `component:Timer` | Stable    | Non-finite values fall back to mount time                  |
+| Duration format | `elapsed`, `clock`                        | Compact units or stopwatch notation                  | Always       | `elapsed`                                                                      | `component:Timer` | Stable    | Types reject other values; runtime falls back to `elapsed` |
+| Typography      | `type`, `size`, `color`, `weight`         | Same Text-backed surface and resolution as Timestamp | Always       | Timestamp defaults: supporting type, secondary color, type-derived size/weight | Timestamp/Text    | Stable    | Existing Text type behavior                                |
+| Time surface    | `<time>` with visible text and `dateTime` | Semantic elapsed duration and time-element props/ref | Always       | Selected format's zero value and `PT0S` before client synchronization          | `component:Timer` | Stable    | Timer-owned `dateTime` wins                                |
+
+## Behavioral and layout contract
+
+| ID   | Candidate invariant                                                                                                                                                                                                                                                                | Basis                        | Draft review state |
+| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | ------------------ |
+| FR1  | Timer MUST render one `<time>` element with selected-format text and matching non-negative ISO 8601 duration.                                                                                                                                                                      | `spec:AST-037` FR1, FR3, FR5 | Settled            |
+| FR2  | Omitted or non-finite `startTime` MUST use the mount origin; a finite value MUST use that caller origin.                                                                                                                                                                           | `spec:AST-037` FR2           | Settled            |
+| FR3  | Ticks MUST recompute from the clock and origin, directly update the owned node, and produce zero React update commits.                                                                                                                                                             | `spec:AST-037` FR3–FR4       | Settled            |
+| FR4  | Prop changes MUST take effect without remounting or duplicate resources; every setup MUST clean up its resource.                                                                                                                                                                   | `spec:AST-037` FR6–FR7       | Settled            |
+| FR5  | `type`, `size`, `color`, `weight`, `xstyle`, `className`, and `style` MUST resolve on the Text wrapper exactly as Timestamp does; other admitted DOM, data, ARIA, and event props and the ref MUST reach `<time>`.                                                                 | `spec:AST-037` FR8           | Settled            |
+| FR6  | Timer MUST NOT add live-region semantics by default.                                                                                                                                                                                                                               | `spec:AST-037` FR9           | Settled            |
+| FR7  | The Text wrapper MUST carry exactly the `timer` target for this component.                                                                                                                                                                                                         | `spec:AST-037` FR10          | Settled            |
+| FR8  | Initial markup MUST use the selected format's zero value and `PT0S` without exposing a clock read in rendered markup.                                                                                                                                                              | `spec:AST-037` FR11          | Settled            |
+| FR9  | `elapsed` and `clock` MUST update on second boundaries below one hour; `elapsed` MUST update on minute boundaries at or above one hour while `clock` remains second-precise. A future origin MUST schedule toward its first visible change rather than waking each second at zero. | `spec:AST-037` FR12          | Settled            |
+| FR10 | Timer SHOULD skip DOM writes while the represented text and duration are unchanged.                                                                                                                                                                                                | `spec:AST-037` FR13          | Settled            |
+
+### Allowed variation
+
+- **AV1 — Scheduling mechanism.** The private browser scheduling mechanism may
+  change while format-aware cadence, clock derivation, no-render ticks, and
+  complete cleanup remain true.
+- **AV2 — Composition.** Callers may use the supported typography and styling
+  inputs without changing timing behavior.
+
+### Representative states
+
+| State            | Required invariant                                             | Allowed variation                       |
+| ---------------- | -------------------------------------------------------------- | --------------------------------------- |
+| Initial elapsed  | `0s` and `PT0S` on one `<time>`                                | Root props and styling                  |
+| Initial clock    | `0:00` and `PT0S` on one `<time>`                              | Root props and styling                  |
+| Seconds/minutes  | `34s`, `2m 08s`, `0:34`, or `2:08` with whole-second semantics | Finite elapsed value                    |
+| Hour-scale       | `1h 02m` at minute cadence or `1:02:33` at second cadence      | Format                                  |
+| Delayed callback | Catch up to clock without accumulated drift                    | Delay length                            |
+| Prop update      | New origin or format applies on the same `<time>`              | Parent render cause                     |
+| Replay/unmount   | Each acquired resource is released                             | Development replay count                |
+| Typography       | Timestamp defaults or explicit Text-family overrides           | Supported type, size, color, and weight |
+
+### Transformation and precedence order
+
+- **ORD1 — Resolve → calculate → clamp → floor to visible precision → format →
+  write → schedule next visible boundary.** Apply the pipeline from `spec:AST-037`
+  to visible text and machine-readable duration.
+- **ORD2 — Timestamp styling split.** Typography, `xstyle`, `className`, `style`,
+  and the `timer` target compose on the Text wrapper. Time-element props and the ref
+  compose on `<time>`; Timer owns `dateTime`.
+
+### Performance and resources
+
+- **PR1 — No tick renders.** Advancing time produces zero React update commits.
+- **PR2 — One resource.** Each mounted Timer owns at most one active timer resource,
+  and each setup cleanup releases its resource.
+- **PR3 — Visible cadence.** Elapsed output at or above one hour does not wake for
+  hidden second changes; clock output remains second-precise.
+- **PR4 — Bounded writes.** Unchanged represented text and duration are not rewritten.
+
+## Accessibility contract
+
+- **AR1 — Semantic duration.** The `<time>` element exposes the current non-negative
+  ISO 8601 duration at the same precision as its visible output.
+- **AR2 — Quiet by default.** No role or `aria-live` value is added automatically;
+  deliberate caller ARIA passes through.
+- **AR3 — Perceivable text.** The formatted duration remains real text content.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                                                                                 | Representation authority                   | Hierarchy role | Component contract      |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------ | -------------- | ----------------------- |
+| Elapsed time     | One stable inline duration with Timestamp-equivalent supporting typography by default and standard Text overrides. | `spec:AST-037/DEC-1`, `spec:AST-037/DEC-3` | Supporting     | FR1, FR3, FR5, AR1, AR3 |
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Elapsed time": {"target": "timer"}
+}
+```
+
+## Family and system relationships
+
+- Timer and Timestamp are temporal Text-family content components: Timer owns
+  durations; Timestamp owns instants. Their typography API and defaults match.
+- `spec:AST-037` owns the public behavior, API, accessibility, performance, and
+  first-Core-admission decisions projected here.
+- `architecture:public-component-api` owns exports, BaseProps, styling, ref, and
+  caller-choice rules.
+- `architecture:react-component-runtime` owns Effect and resource lifecycle.
+- `architecture:component-theming-surface` owns target qualification.
+
+## Verification map
+
+| Contract                    | Verification                                                                     | Representative states                                                                                                        | Mutation or failure expectation                                                                                                                                            | Audit section               |
+| --------------------------- | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
+| FR1–FR4, FR8–FR10, AR1, AR3 | `Timer.test.tsx` controlled-clock tests                                          | Initial formats, origin variants including future scheduling, delayed callback, format change, second/minute/hour boundaries | State ticks, callback accumulation, wrong ladder/padding, negative values, needless pre-origin wakes, stale semantics, wrong cadence, or clock-derived initial markup fail | `audit:Timer/behavior`      |
+| FR3, PR1                    | React Profiler commit-count test                                                 | Several ticks                                                                                                                | A state-based implementation adds update commits and fails                                                                                                                 | `audit:Timer/performance`   |
+| FR4, PR2                    | Resource spies under rerender, StrictMode, and unmount                           | Setup, dependency change, replay, cleanup                                                                                    | Duplicate or leaked resources fail counts                                                                                                                                  | `audit:Timer/resources`     |
+| FR5                         | Public import, Timestamp-default typography, overrides, BaseProps, and ref tests | Default and explicit typography, ref, event, ARIA, class, style                                                              | Missing export, styling divergence, or dropped input fails                                                                                                                 | `audit:Timer/api`           |
+| FR6, AR2                    | Accessibility attribute tests                                                    | Default and deliberate caller ARIA                                                                                           | Unsolicited live semantics or dropped ARIA fails                                                                                                                           | `audit:Timer/accessibility` |
+| FR7                         | `themingTargets.test.ts` and `scripts/check-knowledge.mjs`                       | One wrapper target                                                                                                           | Missing, extra, or misplaced target fails                                                                                                                                  | `audit:Timer/theming`       |
+
+## Decision log
+
+No additional decision. This component projects `spec:AST-037` without widening it.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer examples, implementation code, private
+scheduling mechanics, measurements, or system rules. It links to their owners.

package/src/Timer/Timer.test.tsx

@@ -0,0 +1,302 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Timer.test.tsx
+ * @input Uses React Testing Library, fake clocks, React Profiler, and Timer
+ * @output Verifies formats, adaptive cadence, render isolation, typography, resources, semantics, and passthrough
+ */
+
+import {Profiler, StrictMode, createRef} from 'react';
+import {renderToString} from 'react-dom/server';
+import {act, fireEvent, render, screen} from '@testing-library/react';
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+import {Timer} from './Timer';
+
+describe('Timer', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2026-09-22T00:00:00Z'));
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it('renders deterministic zero-duration markup for each standard format', () => {
+    const {rerender} = render(<Timer data-testid="timer" />);
+    const timer = screen.getByTestId('timer');
+
+    expect(timer.tagName).toBe('TIME');
+    expect(timer).toHaveTextContent('0s');
+    expect(timer).toHaveAttribute('datetime', 'PT0S');
+
+    rerender(<Timer format="clock" data-testid="timer" />);
+    expect(timer).toHaveTextContent('0:00');
+    expect(timer).toHaveAttribute('datetime', 'PT0S');
+  });
+
+  it('keeps server markup independent of the clock', () => {
+    const firstMarkup = renderToString(<Timer startTime={0} />);
+    const firstClockMarkup = renderToString(
+      <Timer startTime={0} format="clock" />,
+    );
+
+    vi.setSystemTime(new Date('2030-01-01T00:00:00Z'));
+    const secondMarkup = renderToString(<Timer startTime={0} />);
+    const secondClockMarkup = renderToString(
+      <Timer startTime={0} format="clock" />,
+    );
+
+    expect(firstMarkup).toBe(secondMarkup);
+    expect(firstMarkup).toContain('dateTime="PT0S"');
+    expect(firstMarkup).toContain('>0s</time>');
+    expect(firstClockMarkup).toBe(secondClockMarkup);
+    expect(firstClockMarkup).toContain('>0:00</time>');
+  });
+
+  it('derives elapsed time from the clock without accumulating callback count', () => {
+    let scheduledTick: (() => void) | undefined;
+    vi.spyOn(globalThis, 'setTimeout').mockImplementation(callback => {
+      scheduledTick = callback as () => void;
+      return 1 as unknown as ReturnType<typeof setTimeout>;
+    });
+
+    render(<Timer data-testid="timer" />);
+
+    vi.setSystemTime(new Date('2026-09-22T00:00:08.750Z'));
+    act(() => {
+      scheduledTick?.();
+    });
+
+    const timer = screen.getByTestId('timer');
+    expect(timer).toHaveTextContent('8s');
+    expect(timer).toHaveAttribute('datetime', 'PT8S');
+  });
+
+  it('formats elapsed durations across seconds, minutes, and hours', () => {
+    const now = Date.now();
+    const {rerender} = render(
+      <Timer startTime={now - 34_000} data-testid="timer" />,
+    );
+    const timer = screen.getByTestId('timer');
+    expect(timer).toHaveTextContent('34s');
+    expect(timer).toHaveAttribute('datetime', 'PT34S');
+
+    rerender(<Timer startTime={now - 128_000} data-testid="timer" />);
+    expect(timer).toHaveTextContent('2m 08s');
+    expect(timer).toHaveAttribute('datetime', 'PT128S');
+
+    rerender(<Timer startTime={now - 3_753_000} data-testid="timer" />);
+    expect(timer).toHaveTextContent('1h 02m');
+    expect(timer).toHaveAttribute('datetime', 'PT3720S');
+  });
+
+  it('formats clock durations across minutes and hours', () => {
+    const now = Date.now();
+    const {rerender} = render(
+      <Timer format="clock" startTime={now - 128_000} data-testid="timer" />,
+    );
+    const timer = screen.getByTestId('timer');
+    expect(timer).toHaveTextContent('2:08');
+    expect(timer).toHaveAttribute('datetime', 'PT128S');
+
+    rerender(
+      <Timer format="clock" startTime={now - 3_753_000} data-testid="timer" />,
+    );
+    expect(timer).toHaveTextContent('1:02:33');
+    expect(timer).toHaveAttribute('datetime', 'PT3753S');
+  });
+
+  it('uses second cadence until elapsed format reaches an hour, then minute cadence', () => {
+    const setTimeoutSpy = vi.spyOn(globalThis, 'setTimeout');
+    const startTime = Date.now() - 3_599_000;
+    render(<Timer startTime={startTime} data-testid="timer" />);
+    const timer = screen.getByTestId('timer');
+
+    expect(timer).toHaveTextContent('59m 59s');
+    expect(setTimeoutSpy).toHaveBeenLastCalledWith(expect.any(Function), 1000);
+
+    act(() => {
+      vi.advanceTimersByTime(1000);
+    });
+    expect(timer).toHaveTextContent('1h 00m');
+    expect(timer).toHaveAttribute('datetime', 'PT3600S');
+    expect(setTimeoutSpy).toHaveBeenLastCalledWith(
+      expect.any(Function),
+      60_000,
+    );
+  });
+
+  it('keeps clock format on second cadence after an hour', () => {
+    const setTimeoutSpy = vi.spyOn(globalThis, 'setTimeout');
+    render(
+      <Timer
+        format="clock"
+        startTime={Date.now() - 3_723_000}
+        data-testid="timer"
+      />,
+    );
+
+    expect(screen.getByTestId('timer')).toHaveTextContent('1:02:03');
+    expect(setTimeoutSpy).toHaveBeenLastCalledWith(expect.any(Function), 1000);
+  });
+
+  it('counts from a finite caller-provided start time', () => {
+    const now = Date.now();
+    render(<Timer startTime={now - 12_400} data-testid="timer" />);
+
+    expect(screen.getByTestId('timer')).toHaveTextContent('12s');
+    expect(screen.getByTestId('timer')).toHaveAttribute('datetime', 'PT12S');
+  });
+
+  it('returns to the original mount origin when startTime is removed', () => {
+    const mountedAt = Date.now();
+    const {rerender} = render(
+      <Timer startTime={mountedAt - 10_000} data-testid="timer" />,
+    );
+
+    act(() => {
+      vi.advanceTimersByTime(2000);
+    });
+    rerender(<Timer data-testid="timer" />);
+
+    expect(screen.getByTestId('timer')).toHaveTextContent('2s');
+    expect(screen.getByTestId('timer')).toHaveAttribute('datetime', 'PT2S');
+  });
+
+  it('falls back to mount time for a non-finite start time', () => {
+    render(<Timer startTime={Number.NaN} data-testid="timer" />);
+
+    act(() => {
+      vi.advanceTimersByTime(2000);
+    });
+
+    expect(screen.getByTestId('timer')).toHaveTextContent('2s');
+  });
+
+  it('clamps a future origin to zero and schedules its first visible change directly', () => {
+    const setTimeoutSpy = vi.spyOn(globalThis, 'setTimeout');
+    render(<Timer startTime={Date.now() + 5000} data-testid="timer" />);
+
+    expect(screen.getByTestId('timer')).toHaveTextContent('0s');
+    expect(screen.getByTestId('timer')).toHaveAttribute('datetime', 'PT0S');
+    expect(setTimeoutSpy).toHaveBeenLastCalledWith(expect.any(Function), 6000);
+
+    act(() => {
+      vi.advanceTimersByTime(6000);
+    });
+
+    expect(screen.getByTestId('timer')).toHaveTextContent('1s');
+    expect(screen.getByTestId('timer')).toHaveAttribute('datetime', 'PT1S');
+  });
+
+  it('updates format without remounting or losing current elapsed time', () => {
+    const now = Date.now();
+    const {rerender} = render(
+      <Timer startTime={now - 3_723_000} data-testid="timer" />,
+    );
+    const timer = screen.getByTestId('timer');
+    expect(timer).toHaveTextContent('1h 02m');
+    expect(timer).toHaveAttribute('datetime', 'PT3720S');
+
+    rerender(
+      <Timer format="clock" startTime={now - 3_723_000} data-testid="timer" />,
+    );
+    expect(screen.getByTestId('timer')).toBe(timer);
+    expect(timer).toHaveTextContent('1:02:03');
+    expect(timer).toHaveAttribute('datetime', 'PT3723S');
+  });
+
+  it('does not schedule React update commits as time advances', () => {
+    const onRender = vi.fn();
+    render(
+      <Profiler id="timer" onRender={onRender}>
+        <Timer />
+      </Profiler>,
+    );
+    expect(onRender).toHaveBeenCalledTimes(1);
+
+    act(() => {
+      vi.advanceTimersByTime(5000);
+    });
+
+    expect(onRender).toHaveBeenCalledTimes(1);
+  });
+
+  it('owns one timer resource and cleans up under StrictMode replay', () => {
+    const setTimeoutSpy = vi.spyOn(window, 'setTimeout');
+    const clearTimeoutSpy = vi.spyOn(window, 'clearTimeout');
+    const {unmount} = render(
+      <StrictMode>
+        <Timer />
+      </StrictMode>,
+    );
+
+    expect(setTimeoutSpy).toHaveBeenCalledTimes(2);
+    expect(clearTimeoutSpy).toHaveBeenCalledTimes(1);
+
+    unmount();
+    expect(clearTimeoutSpy).toHaveBeenCalledTimes(2);
+  });
+
+  it('matches Timestamp typography defaults and accepts overrides', () => {
+    const {rerender} = render(<Timer data-testid="timer" />);
+    const timer = screen.getByTestId('timer');
+    const text = timer.parentElement;
+
+    expect(text).toHaveClass('astryx-text');
+    expect(text).toHaveClass('astryx-timer');
+    expect(text).toHaveAttribute('data-type', 'supporting');
+    expect(text).toHaveAttribute('data-color', 'secondary');
+
+    rerender(
+      <Timer
+        type="body"
+        size="lg"
+        color="primary"
+        weight="bold"
+        data-testid="timer"
+      />,
+    );
+    expect(text).toHaveAttribute('data-type', 'body');
+    expect(text).toHaveAttribute('data-size', 'lg');
+    expect(text).toHaveAttribute('data-color', 'primary');
+  });
+
+  it('forwards its time ref and preserves Timestamp-style root styling and time props', () => {
+    const ref = createRef<HTMLTimeElement>();
+    const onClick = vi.fn();
+    render(
+      <Timer
+        ref={ref}
+        id="elapsed"
+        className="custom-class"
+        style={{color: 'rgb(1, 2, 3)'}}
+        aria-live="polite"
+        onClick={onClick}
+        data-testid="timer"
+      />,
+    );
+
+    const timer = screen.getByTestId('timer');
+    const text = timer.parentElement;
+    expect(ref.current).toBe(timer);
+    expect(timer).toHaveAttribute('id', 'elapsed');
+    expect(text).toHaveClass('astryx-timer');
+    expect(text).toHaveClass('custom-class');
+    expect(text).toHaveStyle({color: 'rgb(1, 2, 3)'});
+    expect(timer).toHaveAttribute('aria-live', 'polite');
+
+    fireEvent.click(timer);
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not add live-region semantics by default', () => {
+    render(<Timer data-testid="timer" />);
+    const timer = screen.getByTestId('timer');
+
+    expect(timer).not.toHaveAttribute('aria-live');
+    expect(timer).not.toHaveAttribute('role');
+  });
+});

package/src/Timer/Timer.tsx

@@ -0,0 +1,258 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file Timer.tsx
+ * @input Uses an optional start time, standardized format, Timestamp typography, BaseProps, and React ref
+ * @output Exports Timer, TimerProps, and TimerFormat with non-rendering elapsed-time updates
+ * @position Core content primitive for elapsed duration in active operations
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Timer/Timer.spec.md
+ * - /packages/core/src/Timer/Timer.doc.mjs
+ * - /packages/core/src/Timer/Timer.test.tsx
+ * - /packages/core/src/Timer/index.ts
+ * - /apps/storybook/stories/Timer.stories.tsx
+ * - /packages/cli/assets/templates/blocks/components/Timer/
+ */
+
+import {useEffect, useRef, useState} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import type {BaseProps} from '../BaseProps';
+import {useMergedRefs} from '../hooks/useMergedRefs';
+import {Text} from '../Text';
+import type {TextColor, TextSize, TextType, TextWeight} from '../theme/types';
+import {mergeProps} from '../utils';
+import {themeProps} from '../utils/themeProps';
+
+const ONE_SECOND_MS = 1000;
+const ONE_MINUTE_MS = 60 * ONE_SECOND_MS;
+const ONE_HOUR_SECONDS = 60 * 60;
+const MAX_TIMEOUT_MS = 2_147_483_647;
+
+const styles = stylex.create({
+  time: {
+    color: 'inherit',
+    display: 'inline',
+    fontFamily: 'inherit',
+    fontSize: 'inherit',
+    fontStyle: 'normal',
+    fontVariantNumeric: 'tabular-nums',
+    fontWeight: 'inherit',
+    lineHeight: 'inherit',
+  },
+});
+
+export type TimerFormat = 'elapsed' | 'clock';
+
+type TimerPresentation = {
+  dateTime: string;
+  text: string;
+};
+
+function pad(value: number): string {
+  return String(value).padStart(2, '0');
+}
+
+function resolveFormat(format: TimerFormat): TimerFormat {
+  return format === 'clock' ? 'clock' : 'elapsed';
+}
+
+function getElapsedMilliseconds(now: number, startTime: number): number {
+  return Math.max(0, now - startTime);
+}
+
+function getPresentation(
+  elapsedMilliseconds: number,
+  format: TimerFormat,
+): TimerPresentation {
+  const elapsedSeconds = Math.floor(elapsedMilliseconds / ONE_SECOND_MS);
+
+  if (format === 'clock') {
+    const hours = Math.floor(elapsedSeconds / ONE_HOUR_SECONDS);
+    const minutes = Math.floor((elapsedSeconds % ONE_HOUR_SECONDS) / 60);
+    const seconds = elapsedSeconds % 60;
+    return {
+      dateTime: `PT${elapsedSeconds}S`,
+      text:
+        hours > 0
+          ? `${String(hours)}:${pad(minutes)}:${pad(seconds)}`
+          : `${String(minutes)}:${pad(seconds)}`,
+    };
+  }
+
+  if (elapsedSeconds < 60) {
+    return {
+      dateTime: `PT${elapsedSeconds}S`,
+      text: `${String(elapsedSeconds)}s`,
+    };
+  }
+
+  const totalMinutes = Math.floor(elapsedSeconds / 60);
+  if (totalMinutes < 60) {
+    return {
+      dateTime: `PT${elapsedSeconds}S`,
+      text: `${String(totalMinutes)}m ${pad(elapsedSeconds % 60)}s`,
+    };
+  }
+
+  const representedSeconds = totalMinutes * 60;
+  return {
+    dateTime: `PT${representedSeconds}S`,
+    text: `${String(Math.floor(totalMinutes / 60))}h ${pad(totalMinutes % 60)}m`,
+  };
+}
+
+function getMillisecondsUntilNextChange(
+  now: number,
+  startTime: number,
+  elapsedMilliseconds: number,
+  format: TimerFormat,
+): number {
+  if (now < startTime) {
+    return Math.min(startTime - now + ONE_SECOND_MS, MAX_TIMEOUT_MS);
+  }
+
+  const precision =
+    format === 'elapsed' &&
+    elapsedMilliseconds >= ONE_HOUR_SECONDS * ONE_SECOND_MS
+      ? ONE_MINUTE_MS
+      : ONE_SECOND_MS;
+  return precision - (elapsedMilliseconds % precision);
+}
+
+export interface TimerProps extends Omit<
+  BaseProps<HTMLTimeElement>,
+  'dateTime'
+> {
+  /** Ref forwarded to the rendered `<time>` element. */
+  ref?: React.Ref<HTMLTimeElement>;
+  /**
+   * Unix time in milliseconds when the measured operation began. Omit it to
+   * start counting from this Timer's mount.
+   */
+  startTime?: number;
+  /**
+   * Standard duration representation.
+   * @default 'elapsed'
+   */
+  format?: TimerFormat;
+  /**
+   * Semantic text type. Matches Timestamp typography behavior.
+   * @default 'supporting'
+   */
+  type?: TextType;
+  /** Explicit font size override. Overrides the size from `type`. */
+  size?: TextSize;
+  /**
+   * Text color.
+   * @default 'secondary'
+   */
+  color?: TextColor;
+  /** Font weight override. */
+  weight?: TextWeight;
+}
+
+/**
+ * Displays a standardized elapsed duration without scheduling React tick renders.
+ *
+ * Timer writes changing text and its ISO 8601 duration directly to the owned
+ * `<time>` node. Use `elapsed` for compact duration text or `clock` for a
+ * stopwatch-like reading.
+ *
+ * @example
+ * ```
+ * <Timer />
+ * <Timer format="clock" />
+ * ```
+ */
+export function Timer({
+  startTime,
+  format = 'elapsed',
+  type = 'supporting',
+  size,
+  color = 'secondary',
+  weight,
+  ref,
+  xstyle,
+  className,
+  style,
+  ...rest
+}: TimerProps) {
+  const [mountTime] = useState(() => Date.now());
+  const timerRef = useRef<HTMLTimeElement>(null);
+  const mergedRef = useMergedRefs(ref, timerRef);
+  const resolvedFormat = resolveFormat(format);
+  const initialPresentation = getPresentation(0, resolvedFormat);
+
+  useEffect(() => {
+    const resolvedStartTime =
+      startTime !== undefined && Number.isFinite(startTime)
+        ? startTime
+        : mountTime;
+    let timeoutID: ReturnType<typeof setTimeout> | undefined;
+    let previousDateTime: string | undefined;
+    let previousText: string | undefined;
+
+    const tick = () => {
+      const now = Date.now();
+      const elapsedMilliseconds = getElapsedMilliseconds(
+        now,
+        resolvedStartTime,
+      );
+      const presentation = getPresentation(elapsedMilliseconds, resolvedFormat);
+      const node = timerRef.current;
+
+      if (node != null) {
+        if (presentation.text !== previousText) {
+          node.textContent = presentation.text;
+          previousText = presentation.text;
+        }
+        if (presentation.dateTime !== previousDateTime) {
+          node.dateTime = presentation.dateTime;
+          previousDateTime = presentation.dateTime;
+        }
+      }
+
+      timeoutID = setTimeout(
+        tick,
+        getMillisecondsUntilNextChange(
+          now,
+          resolvedStartTime,
+          elapsedMilliseconds,
+          resolvedFormat,
+        ),
+      );
+    };
+
+    tick();
+    return () => {
+      if (timeoutID !== undefined) {
+        clearTimeout(timeoutID);
+      }
+    };
+  }, [mountTime, resolvedFormat, startTime]);
+
+  const timerProps = mergeProps(themeProps('timer'), {className, style});
+
+  return (
+    <Text
+      type={type}
+      size={size}
+      color={color}
+      weight={weight}
+      xstyle={xstyle}
+      {...timerProps}>
+      <time
+        {...rest}
+        ref={mergedRef}
+        dateTime="PT0S"
+        {...stylex.props(styles.time)}>
+        {initialPresentation.text}
+      </time>
+    </Text>
+  );
+}
+
+Timer.displayName = 'Timer';

package/src/Timer/index.ts

@@ -0,0 +1,11 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file index.ts
+ * @input Imports Timer, TimerProps, and TimerFormat
+ * @output Public Timer component barrel
+ * @position Component subpath entry point for @astryxdesign/core/Timer
+ */
+
+export {Timer} from './Timer';
+export type {TimerFormat, TimerProps} from './Timer';

package/src/index.ts

@@ -161,6 +161,9 @@ export * from './Spinner';
 // Timestamp display
 export * from './Timestamp';
 
+// Elapsed timer display
+export * from './Timer';
+
 // Overlay
 export * from './Overlay';
 export * from './Outline';