You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@causeway.apache.org by da...@apache.org on 2026/08/29 10:01:02 UTC

(causeway) 01/07: docs(openspec): propose breadcrumbs web component

This is an automated email from the ASF dual-hosted git repository.

danhaywood pushed a commit to branch htmx
in repository https://gitbox.apache.org/repos/asf/causeway.git

commit 286f5d0d6f31b558aeca07d58a9914ee3af72d0b
Author: Dan Haywood <da...@haywood-associates.co.uk>
AuthorDate: Sat Aug 29 09:59:25 2026 +0200

    docs(openspec): propose breadcrumbs web component
---
 .../add-breadcrumbs-web-component/.openspec.yaml   |  2 +
 .../add-breadcrumbs-web-component/design.md        | 99 ++++++++++++++++++++++
 .../add-breadcrumbs-web-component/proposal.md      | 31 +++++++
 .../specs/domain-web-components/spec.md            | 57 +++++++++++++
 .../generic-htmx-web-component-viewer/spec.md      | 35 ++++++++
 .../specs/graphql-web-component-context/spec.md    | 40 +++++++++
 .../rich-graphql-navigable-breadcrumbs/spec.md     | 64 ++++++++++++++
 .../changes/add-breadcrumbs-web-component/tasks.md | 36 ++++++++
 8 files changed, 364 insertions(+)

diff --git a/openspec/changes/add-breadcrumbs-web-component/.openspec.yaml b/openspec/changes/add-breadcrumbs-web-component/.openspec.yaml
new file mode 100644
index 00000000000..50adc91034f
--- /dev/null
+++ b/openspec/changes/add-breadcrumbs-web-component/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-08-29
diff --git a/openspec/changes/add-breadcrumbs-web-component/design.md b/openspec/changes/add-breadcrumbs-web-component/design.md
new file mode 100644
index 00000000000..5af7296504d
--- /dev/null
+++ b/openspec/changes/add-breadcrumbs-web-component/design.md
@@ -0,0 +1,99 @@
+## Context
+
+Causeway's metamodel already resolves one navigable parent for an object through `ObjectSpecification.getNavigableParent(Object)`, backed by `NavigableParentFacet` and normally declared with `@PropertyLayout(navigable = Navigable.PARENT)`.
+The rich GraphQL `_meta` object currently exposes the current object's bookmark identity and title, but no navigable hierarchy.
+The browser object context coordinates metadata and member selections for semantic consumers such as `<cw-object-header>`, while `<cw-object-link>` already owns framework-neutral navigation events.
+
+The feature crosses metamodel-backed GraphQL resolution, targeted schema discovery, coordinated browser projection, component rendering, HTMX navigation, and the Petclinic sample.
+It must remain bounded, authorization-safe, cycle-safe, framework-neutral, and compatible with clients that do not select the new field.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Project the current object's navigable ancestors from the established Causeway facet.
+- Give `<cw-breadcrumbs>` one semantic context requirement and no knowledge of generated GraphQL names.
+- Render accessible root-to-current breadcrumbs using existing semantic object links and navigation events.
+- Demonstrate owner → pet → visit hierarchy in Petclinic.
+- Keep schema discovery, runtime traversal, response size, and diagnostics bounded.
+
+**Non-Goals:**
+
+- Infer hierarchy from arbitrary references, JPA relationships, collections, URLs, or browser history.
+- Persist, cache globally, or mutate breadcrumb relationships.
+- Add an application-specific breadcrumb provider or a second navigation event contract.
+- Make breadcrumbs part of every object header or generic page automatically.
+- Render dropdown ancestors, sibling menus, icons, or an unbounded tree.
+
+## Decisions
+
+### Add a bounded ancestor list beneath rich object metadata
+
+Each generated rich `_meta` type will expose a nullable `breadcrumbs` field containing root-to-immediate-parent entries with non-null `logicalTypeName`, `id`, and `title` fields.
+The current object is not repeated in the list because its existing metadata already supplies identity and title and `<cw-breadcrumbs>` needs to mark it as the non-link current item.
+The shared breadcrumb-entry GraphQL type will be registered once and reused across generated object metadata types.
+
+A metadata list is preferred to recursively returning arbitrary generated rich object types because a navigable parent can have a different logical type at every level and the component needs only navigation identity and title.
+It also permits one bounded object read instead of sequential browser round trips for each ancestor.
+Adding a flag to member metadata is rejected because the runtime hierarchy belongs to the object and the navigable-parent facet can be imperative.
+
+### Traverse on the server through the existing facet
+
+`CommonMetaFetcher` will start from the current managed object, call `objSpec().getNavigableParent(pojo)`, adapt each returned parent, obtain its bookmark and title, and repeat from that parent.
+Traversal will stop at a null parent or an unavailable bookmark.
+It will preserve ancestor order by collecting upward and reversing the result before returning it.
+
+The traversal will accept at most 32 ancestors and track bookmark identities already visited, including the current object.
+A cycle, facet exception, or depth overflow will fail only the nullable `breadcrumbs` field with a bounded safe GraphQL error rather than returning a misleading partial chain or invalidating sibling metadata fields.
+No Java class names, arbitrary object strings, or exception details will enter the client diagnostic.
+
+The bound is fixed rather than configurable because it is a protocol safety limit, not an application presentation preference.
+Client-side traversal is rejected because it multiplies requests and asks the browser to reproduce server metamodel semantics.
+
+### Treat breadcrumbs as one semantic context requirement
+
+`ObjectContextController` will accept `{kind: 'breadcrumbs'}` and translate it to the current metadata identity, title, and nested breadcrumb entry selection.
+Targeted introspection will include the breadcrumb-entry object type only when reached from metadata.
+The requirement will participate in the existing initial coalescing, delta loading, refresh, cancellation, immutable snapshots, and metadata-path partial-error behavior.
+
+A standalone component issuing GraphQL directly is rejected because it would bypass context coordination and duplicate generated-name handling.
+Piggybacking every header read is rejected because pages that do not contain breadcrumbs should incur no breadcrumb traversal or response bytes.
+
+### Compose existing semantic links
+
+`<cw-breadcrumbs>` will extend `CausewayContextConsumerElement`, register the breadcrumbs requirement, and render a `<nav aria-label="Breadcrumb">` containing an ordered list.
+Each ancestor will be represented by `<cw-object-link>` using returned identity and title, while the current object will be escaped text marked with `aria-current="page"`.
+The component therefore reuses the established bubbling and composed `causeway-navigation-request` event and remains independent of HTMX and URL formats.
+
+The component will render local loading, unsupported, partial-error, and terminal-error states consistently with other consumers.
+With no ancestors it will render only the current item rather than disappear, so assistive technology retains a stable location landmark.
+Malformed entries will be omitted defensively, but the server contract and tests remain authoritative.
+
+### Use opt-in page composition
+
+The component will be registered, exported, documented, and styled as part of the public foundation vocabulary, but it will not be inserted automatically by `<cw-object>` or the HTMX viewer.
+Applications decide where breadcrumbs belong by writing `<cw-breadcrumbs></cw-breadcrumbs>` in custom HTML or another host composition.
+
+Petclinic will mark `Pet.petOwner` and `Visit.pet` as `Navigable.PARENT` and include the component on its custom object pages.
+The owner has no parent, a pet has its owner, and a visit has its pet and owner, providing deterministic zero-, one-, and two-ancestor coverage.
+HTMX's existing semantic navigation bridge will turn ancestor link events into canonical routes without component-specific integration.
+
+## Risks / Trade-offs
+
+- [Risk] An imperative parent method can be expensive or throw. → Evaluate it only when breadcrumbs are selected, bound traversal to 32, and isolate failures to the nullable metadata field.
+- [Risk] Cyclic parent relationships could loop or produce misleading navigation. → Track bookmarks, reject cycles with a bounded diagnostic, and never return a truncated cycle.
+- [Risk] A parent cannot be bookmarked. → Stop before that parent because no stable semantic navigation target exists.
+- [Risk] Ancestor titles can vary by locale or state. → Resolve titles per request through the current managed objects and do not globally cache chains.
+- [Risk] Adding a nested metadata type expands targeted introspection. → Discover exactly one shared support type only for consumers that register breadcrumbs.
+- [Risk] Petclinic hierarchy annotations can affect other Causeway viewers. → Use the standard existing `Navigable.PARENT` semantic intentionally and cover Wicket/HTMX startup and navigation regressions.
+- [Risk] Long titles can distort responsive layout. → Use wrapping and overflow-safe CSS while preserving full escaped accessible text.
+
+## Migration Plan
+
+Add the optional GraphQL field, then add browser discovery and context support, then register the component, and finally opt Petclinic pages and domain properties into the feature.
+Existing GraphQL documents, components, and pages remain unchanged unless they select or compose breadcrumbs.
+Rollback removes `<cw-breadcrumbs>` from application pages and the Petclinic navigable annotations; the additive GraphQL field can remain without affecting clients.
+
+## Open Questions
+
+None.
diff --git a/openspec/changes/add-breadcrumbs-web-component/proposal.md b/openspec/changes/add-breadcrumbs-web-component/proposal.md
new file mode 100644
index 00000000000..ffc8ade6ca2
--- /dev/null
+++ b/openspec/changes/add-breadcrumbs-web-component/proposal.md
@@ -0,0 +1,31 @@
+## Why
+
+Causeway already models an object's navigable parent through `@PropertyLayout(navigable = Navigable.PARENT)`, but the rich GraphQL and web-component stack does not expose that hierarchy to custom pages.
+Applications therefore cannot provide consistent, metadata-driven breadcrumbs without duplicating parent relationships and navigation logic in application-specific code.
+
+## What Changes
+
+- Add a bounded rich GraphQL metadata projection for the current object's navigable ancestor chain, derived from the existing navigable-parent facet.
+- Add a semantic breadcrumbs read requirement to the shared object context so descendant components do not construct GraphQL selections.
+- Introduce the framework-neutral `<cw-breadcrumbs>` custom element with accessible root-to-current navigation and standard semantic navigation events.
+- Bound ancestor traversal, detect cycles, omit unavailable identities safely, and preserve GraphQL authorization and partial-error behavior.
+- Add stable component names, classes, styling, documentation, fixtures, and automated tests.
+- Mark Petclinic's `Pet.petOwner` and `Visit.pet` properties as navigable parents and compose `<cw-breadcrumbs>` into its HTML-authored pages.
+- Extend Petclinic integration and Playwright coverage for owner → pet → visit breadcrumb hierarchy and navigation.
+
+## Capabilities
+
+### New Capabilities
+
+- `rich-graphql-navigable-breadcrumbs`: Expose a bounded root-to-parent identity and title chain from Causeway's navigable-parent facet through rich object metadata.
+
+### Modified Capabilities
+
+- `graphql-web-component-context`: Add a semantic breadcrumbs requirement to coordinated rich object reads.
+- `domain-web-components`: Add the accessible framework-neutral `<cw-breadcrumbs>` component and its semantic navigation behavior.
+- `generic-htmx-web-component-viewer`: Demonstrate metadata-driven breadcrumbs and canonical navigation in the Petclinic HTML-authored pages.
+
+## Impact
+
+The change affects rich GraphQL common object metadata and tests, web-component schema discovery, object-context projection and component registration, component styles and documentation, package fixtures and browser tests, Petclinic domain annotations and HTML pages, HTMX route navigation coverage, and the generated GraphQL contract.
+No new third-party dependency, route format, application-specific breadcrumb API, or direct browser access to metamodel services is introduced.
diff --git a/openspec/changes/add-breadcrumbs-web-component/specs/domain-web-components/spec.md b/openspec/changes/add-breadcrumbs-web-component/specs/domain-web-components/spec.md
new file mode 100644
index 00000000000..49cfbc1bb5d
--- /dev/null
+++ b/openspec/changes/add-breadcrumbs-web-component/specs/domain-web-components/spec.md
@@ -0,0 +1,57 @@
+## ADDED Requirements
+
+### Requirement: Semantic object breadcrumbs
+The component library SHALL provide a framework-neutral `<cw-breadcrumbs>` custom element that consumes the nearest object context's semantic breadcrumbs requirement and renders the navigable ancestor chain followed by the current object.
+
+#### Scenario: Object has multiple ancestors
+- **WHEN** `<cw-breadcrumbs>` receives root-to-parent entries and current-object metadata
+- **THEN** it renders each ancestor as a semantic `<cw-object-link>` in the supplied order
+- **AND** renders the escaped current title as the final non-link item marked `aria-current="page"`
+
+#### Scenario: Object has no ancestors
+- **WHEN** the breadcrumb list is empty and current-object metadata is available
+- **THEN** the component renders a stable breadcrumb landmark containing only the current item
+
+#### Scenario: Ancestor entry is malformed
+- **WHEN** an entry lacks a logical type name, identifier, or title
+- **THEN** the component omits that entry defensively
+- **AND** does not construct a partial navigation target
+
+### Requirement: Accessible breadcrumb presentation
+`<cw-breadcrumbs>` SHALL render keyboard-operable, escaped, responsive light-DOM markup with a `nav` landmark labelled `Breadcrumb`, an ordered list, documented semantic classes, and ordinary link focus behavior.
+
+#### Scenario: Assistive technology inspects breadcrumbs
+- **WHEN** breadcrumb state is ready
+- **THEN** the navigation landmark and list communicate hierarchy order
+- **AND** exactly one final current item exposes `aria-current="page"`
+
+#### Scenario: Breadcrumb title is long or contains markup-like text
+- **WHEN** an ancestor or current title contains long text or HTML-significant characters
+- **THEN** the title is escaped as text and wraps without causing horizontal page overflow
+
+### Requirement: Existing semantic navigation ownership
+Ancestor activation SHALL use the existing bubbling and composed `causeway-navigation-request` contract produced by `<cw-object-link>` and SHALL NOT impose a URL, router, HTMX, or application callback API.
+
+#### Scenario: User activates an ancestor
+- **WHEN** the user follows an ancestor breadcrumb by pointer or keyboard
+- **THEN** one semantic navigation event identifies that ancestor's logical type, id, and title
+- **AND** the host remains responsible for route handling
+
+### Requirement: Local breadcrumb states
+`<cw-breadcrumbs>` SHALL render loading, unsupported, partial-error, and terminal-error states locally without suppressing successful sibling components.
+
+#### Scenario: Breadcrumb traversal is loading
+- **WHEN** the semantic requirement is awaiting schema or object data
+- **THEN** the component exposes a bounded busy status within its own landmark
+
+#### Scenario: Breadcrumb traversal fails
+- **WHEN** the requirement reports unsupported, partial-error, or terminal-error state
+- **THEN** the component renders a bounded accessible local diagnostic
+- **AND** does not render stale ancestor links
+
+### Requirement: Public breadcrumb component contract
+The component registry, ECMAScript exports, semantic element-name constants, stylesheet surfaces, usage documentation, fixtures, and automation hooks SHALL include `<cw-breadcrumbs>` without changing existing component contracts.
+
+#### Scenario: Application uses plain HTML
+- **WHEN** an application imports the standard foundation entry module and writes `<cw-breadcrumbs>` beneath an object context
+- **THEN** the element is registered and operates without a frontend framework or direct GraphQL document construction
diff --git a/openspec/changes/add-breadcrumbs-web-component/specs/generic-htmx-web-component-viewer/spec.md b/openspec/changes/add-breadcrumbs-web-component/specs/generic-htmx-web-component-viewer/spec.md
new file mode 100644
index 00000000000..e11309973af
--- /dev/null
+++ b/openspec/changes/add-breadcrumbs-web-component/specs/generic-htmx-web-component-viewer/spec.md
@@ -0,0 +1,35 @@
+## ADDED Requirements
+
+### Requirement: Petclinic navigable breadcrumbs demonstration
+The Petclinic HTMX sample SHALL demonstrate `<cw-breadcrumbs>` through standard navigable-parent annotations and HTML-authored page composition without application-specific breadcrumb rendering or route code.
+
+#### Scenario: Pet owner page is rendered
+- **WHEN** the Pet Owner custom page renders for Mary Smith
+- **THEN** its breadcrumb landmark contains Mary Smith as the current item with no ancestor link
+
+#### Scenario: Pet page is rendered
+- **WHEN** Mary Smith's pet Basil is rendered
+- **THEN** the breadcrumb landmark contains a Mary Smith ancestor link followed by Basil as the current item
+- **AND** the hierarchy is derived from `Pet.petOwner` marked `Navigable.PARENT`
+
+#### Scenario: Visit page is rendered
+- **WHEN** Basil's scheduled visit is rendered
+- **THEN** the breadcrumb landmark contains Mary Smith and Basil ancestor links in that order followed by the visit as the current item
+- **AND** the hierarchy is derived through `Visit.pet` and then `Pet.petOwner`
+
+#### Scenario: User follows a breadcrumb
+- **WHEN** a user activates the Mary Smith or Basil ancestor link from a descendant route
+- **THEN** the established HTMX semantic navigation bridge installs the corresponding canonical object route
+- **AND** no breadcrumb-specific route handler or URL construction is required
+
+### Requirement: Petclinic breadcrumb regression coverage
+Petclinic integration and browser acceptance SHALL verify navigable annotations, rich GraphQL breadcrumb metadata, component rendering, accessibility, responsive presentation, and canonical navigation while retaining existing custom-page behavior.
+
+#### Scenario: Rich GraphQL hierarchy is queried
+- **WHEN** integration coverage reads metadata for owner, pet, and visit fixtures
+- **THEN** it observes deterministic zero-, one-, and two-ancestor breadcrumb chains
+
+#### Scenario: Browser exercises descendant hierarchy
+- **WHEN** browser automation opens pet and visit routes at desktop and mobile widths
+- **THEN** breadcrumb order, current state, focusable links, no-overflow presentation, and navigation are correct
+- **AND** no unexpected console, page, resource, or GraphQL failure is observed
diff --git a/openspec/changes/add-breadcrumbs-web-component/specs/graphql-web-component-context/spec.md b/openspec/changes/add-breadcrumbs-web-component/specs/graphql-web-component-context/spec.md
new file mode 100644
index 00000000000..05d74682617
--- /dev/null
+++ b/openspec/changes/add-breadcrumbs-web-component/specs/graphql-web-component-context/spec.md
@@ -0,0 +1,40 @@
+## ADDED Requirements
+
+### Requirement: Semantic breadcrumbs requirement
+The object context SHALL accept a semantic breadcrumbs read requirement and SHALL translate it to the supported current-object identity, title, and navigable-ancestor metadata fields without exposing generated GraphQL names to the consumer.
+
+#### Scenario: Breadcrumb consumer joins initial composition
+- **WHEN** a breadcrumbs consumer and other domain components register during the same rendering turn
+- **THEN** the context coalesces their selections into one initial object operation
+- **AND** breadcrumb metadata is returned through the consumer's local requirement state
+
+#### Scenario: Breadcrumb consumer connects later
+- **WHEN** breadcrumbs are registered after an object snapshot already exists without their selection
+- **THEN** the context loads only the missing metadata selection
+- **AND** merges it into the immutable current snapshot
+
+#### Scenario: Breadcrumb consumer disconnects
+- **WHEN** the consumer releases its requirement
+- **THEN** the requirement is omitted from subsequent complete refresh projections
+- **AND** release alone causes no network request
+
+### Requirement: Targeted breadcrumb schema discovery
+The GraphQL client SHALL discover the shared breadcrumb-entry object type through targeted introspection only when it is reachable from requested object metadata.
+
+#### Scenario: Metadata supports breadcrumb entries
+- **WHEN** an object description exposes `breadcrumbs` as a list of breadcrumb-entry objects
+- **THEN** targeted discovery loads that entry type and its supported fields
+- **AND** the semantic requirement selects only supported identity and title fields
+
+#### Scenario: Schema lacks breadcrumb support
+- **WHEN** the introspected metadata type has no `breadcrumbs` field or no usable entry identity fields
+- **THEN** the breadcrumb requirement reports an unsupported local state
+- **AND** existing header and member requirements remain usable
+
+### Requirement: Breadcrumb partial-error isolation
+The object context SHALL associate a GraphQL error on navigable breadcrumb metadata with the breadcrumbs requirement while preserving successful sibling metadata and member state.
+
+#### Scenario: Ancestor traversal fails
+- **WHEN** the object response contains current metadata and member data plus an error at the breadcrumb field path
+- **THEN** the breadcrumbs consumer receives a partial-error state
+- **AND** successful header, property, action, and collection consumers retain their normal state
diff --git a/openspec/changes/add-breadcrumbs-web-component/specs/rich-graphql-navigable-breadcrumbs/spec.md b/openspec/changes/add-breadcrumbs-web-component/specs/rich-graphql-navigable-breadcrumbs/spec.md
new file mode 100644
index 00000000000..71d8afa0c08
--- /dev/null
+++ b/openspec/changes/add-breadcrumbs-web-component/specs/rich-graphql-navigable-breadcrumbs/spec.md
@@ -0,0 +1,64 @@
+## ADDED Requirements
+
+### Requirement: Navigable ancestor metadata
+Each rich GraphQL object metadata type SHALL expose a nullable `breadcrumbs` field containing the current object's navigable ancestors as shared breadcrumb-entry objects with non-null `logicalTypeName`, `id`, and `title` fields.
+The entries MUST be ordered from the root ancestor to the immediate parent and MUST NOT repeat the current object.
+
+#### Scenario: Object has a navigable hierarchy
+- **WHEN** the current object's metamodel resolves a parent and that parent resolves another parent
+- **THEN** `breadcrumbs` returns both bookmarkable ancestors in root-to-parent order
+- **AND** each entry contains its current request-local title and bookmark identity
+
+#### Scenario: Object has no navigable parent
+- **WHEN** the current object's metamodel resolves no navigable parent
+- **THEN** `breadcrumbs` returns an empty list
+- **AND** existing current-object metadata remains unchanged
+
+#### Scenario: Navigable parent is unavailable as a navigation target
+- **WHEN** parent traversal reaches null or an object without a bookmark identity
+- **THEN** traversal stops before adding an unusable entry
+- **AND** no Java class name or arbitrary object string is exposed
+
+### Requirement: Facet-authoritative hierarchy traversal
+The rich GraphQL metadata resolver SHALL derive each parent only through the current object's established navigable-parent metamodel semantic, including `@PropertyLayout(navigable = Navigable.PARENT)`, and SHALL NOT infer parents from arbitrary reference properties or persistence relationships.
+
+#### Scenario: Property is the declared navigable parent
+- **WHEN** a domain property is marked `Navigable.PARENT`
+- **THEN** breadcrumb traversal follows the parent returned by the corresponding navigable-parent facet
+- **AND** no duplicate application breadcrumb declaration is required
+
+#### Scenario: Ordinary reference is present
+- **WHEN** an object has a reference property that is not its navigable parent
+- **THEN** that reference does not appear in the breadcrumb chain merely because it is reachable
+
+### Requirement: Bounded and cycle-safe traversal
+Breadcrumb traversal MUST inspect no more than 32 ancestors and MUST detect repeated bookmark identities, including repetition of the current object.
+A cycle, depth overflow, or facet failure SHALL produce a bounded safe error on the nullable `breadcrumbs` field rather than an unbounded operation or a misleading truncated chain.
+
+#### Scenario: Hierarchy contains a cycle
+- **WHEN** traversal encounters an identity already present in the active chain
+- **THEN** the `breadcrumbs` field fails with a bounded cycle diagnostic
+- **AND** traversal terminates without returning the cyclic partial chain
+
+#### Scenario: Hierarchy exceeds the bound
+- **WHEN** traversal would inspect a thirty-third ancestor
+- **THEN** the `breadcrumbs` field fails with a bounded depth diagnostic
+- **AND** it exposes neither the overlong chain nor internal exception details
+
+#### Scenario: Parent facet throws
+- **WHEN** navigable-parent evaluation throws an application exception
+- **THEN** the field reports a bounded safe failure
+- **AND** sibling metadata fields can remain available through GraphQL partial-data behavior
+
+### Requirement: Additive metadata contract
+The breadcrumb projection SHALL be additive to existing rich object metadata and SHALL use one shared breadcrumb-entry GraphQL type rather than one new entry type per domain type.
+
+#### Scenario: Existing client omits breadcrumbs
+- **WHEN** a client executes an established rich object document without selecting `breadcrumbs`
+- **THEN** its operation and response shape remain valid
+- **AND** no navigable-parent traversal occurs
+
+#### Scenario: Schema contains many domain types
+- **WHEN** rich metadata is generated for multiple object types
+- **THEN** all breadcrumb fields reuse the same entry type
+- **AND** schema growth is bounded independently of the domain-type count
diff --git a/openspec/changes/add-breadcrumbs-web-component/tasks.md b/openspec/changes/add-breadcrumbs-web-component/tasks.md
new file mode 100644
index 00000000000..f32917cafed
--- /dev/null
+++ b/openspec/changes/add-breadcrumbs-web-component/tasks.md
@@ -0,0 +1,36 @@
+## 1. Rich GraphQL breadcrumb metadata
+
+- [ ] 1.1 Add one shared GraphQL breadcrumb-entry type and an optional `breadcrumbs` field to generated rich object metadata.
+- [ ] 1.2 Implement root-to-parent traversal through `ObjectSpecification.getNavigableParent`, with bookmark identity, request-local titles, a 32-ancestor bound, cycle detection, and safe failures.
+- [ ] 1.3 Add GraphQL model unit tests for empty, single, multi-level, unbookmarkable, cyclic, over-depth, and throwing parent chains.
+- [ ] 1.4 Extend GraphQL schema and end-to-end contract fixtures to verify additive field shape, shared-type reuse, partial errors, and no traversal when unselected.
+
+## 2. Browser context support
+
+- [ ] 2.1 Extend targeted metadata introspection to discover the shared breadcrumb-entry type without broad schema introspection.
+- [ ] 2.2 Add the semantic breadcrumbs requirement, nested selection translation, state mapping, projection coalescing, delta loading, refresh, and release behavior to `ObjectContextController`.
+- [ ] 2.3 Add browser context and operation tests for supported, unsupported, ready, partial-error, late-registration, and released breadcrumb requirements.
+- [ ] 2.4 Update rich-schema fixtures with deterministic empty, one-level, and multi-level breadcrumb metadata.
+
+## 3. Breadcrumb web component
+
+- [ ] 3.1 Implement and export `<cw-breadcrumbs>` as a context consumer rendering ancestor object links and one escaped current item in an accessible breadcrumb landmark.
+- [ ] 3.2 Register the element and add its public element-name, host-class, stable selector, and semantic navigation contracts.
+- [ ] 3.3 Add responsive breadcrumb styles for ordered separators, focus, wrapping, long titles, narrow layouts, dark mode, and forced colors.
+- [ ] 3.4 Add component tests for loading, empty hierarchy, multiple ancestors, malformed entries, navigation events, escaping, errors, accessibility, and overflow-safe markup.
+- [ ] 3.5 Document plain-HTML usage, GraphQL requirements, hierarchy semantics, error behavior, and framework-neutral navigation ownership.
+
+## 4. Petclinic adoption
+
+- [ ] 4.1 Mark `Pet.petOwner` and `Visit.pet` with the standard `Navigable.PARENT` property-layout semantic.
+- [ ] 4.2 Compose `<cw-breadcrumbs>` into the Pet Owner, Pet, and Visit HTML-authored pages without adding application-specific breadcrumb code.
+- [ ] 4.3 Extend Petclinic GraphQL integration coverage for zero-, one-, and two-ancestor fixture chains and private-page markup coverage for the component.
+- [ ] 4.4 Extend Petclinic Playwright coverage for breadcrumb order, current state, keyboard activation, canonical HTMX navigation, responsive layout, accessibility, and clean browser diagnostics.
+- [ ] 4.5 Update Petclinic documentation and screenshots or stable test hooks where the existing sample contract requires them.
+
+## 5. Validation and archive readiness
+
+- [ ] 5.1 Run focused GraphQL model tests and GraphQL end-to-end tests for breadcrumb metadata.
+- [ ] 5.2 Run foundation unit, component, fixture, lint, and package verification suites.
+- [ ] 5.3 Run HTMX viewer, Petclinic integration, and Petclinic Playwright acceptance suites.
+- [ ] 5.4 Run applicable Maven verification, OpenSpec strict validation, formatting, license, diff, and working-tree checks.