@duffcloudservices/kit 0.1.0

package/README.md

@@ -0,0 +1,48 @@
+# @duffcloudservices/kit
+
+DcsKit Vue runtime — the editable primitives (`DcsText` / `DcsImage` / `DcsSection`,
+authoring sugar over the `[data-dcs-*]` editor-bridge markers) plus the canonical
+cascade-layer contract (`@layer theme, base, components, utilities`). The Vue-side
+companion to `@duffcloudservices/kit-vite` (the Vite plugin bundle / `defineDcsSite()`).
+
+Part of the first-party site-framework initiative — see
+[`.docs/plans/first-party-site-framework/`](../../.docs/plans/first-party-site-framework/).
+
+## Status (milestone M9)
+
+**Publish-ready, first publish is maintainer-gated.** The package builds (`dist/index.js`
++ `dist/style.css` + d.ts), exports the three primitives, and passes 8 Vitest marker
+assertions. `@duffcloudservices/kit-vite` is likewise scaffolded and publish-ready.
+
+## Publishing
+
+The package has **never been published**, so the first publish must be done manually by a
+maintainer with npm credentials (trusted/CI publishing can't be configured on npmjs.com
+until the package exists):
+
+```bash
+cd packages/kit
+npm login            # maintainer npm account
+npm publish --access public
+```
+
+Then configure trusted publishing on npmjs.com (Owner=NateDuff, Repository=dcs,
+Workflow=`npm-publish.yml`) so future releases publish automatically by pushing an
+`npm-v<version>` tag — see [`.github/workflows/npm-publish.yml`](../../.github/workflows/npm-publish.yml).
+
+## Consuming it in a pilot site (after the first publish)
+
+The pilot sites currently consume `@duffcloudservices/cms` from npm and prove the kit
+patterns in-repo. Once `@duffcloudservices/kit` is on npm, swapping a site to consume it
+is a normal semver bump — e.g. Iron Oak's `site/src/kit/index.ts` barrel re-exports from
+`@duffcloudservices/kit` instead of `@duffcloudservices/cms`:
+
+```bash
+cd <site>/site   # e.g. E:/source/repos/handyman-bryan/site
+pnpm add @duffcloudservices/kit@^0.1.0
+# then point site/src/kit/index.ts at @duffcloudservices/kit and `pnpm build` to verify
+```
+
+No `file:` / `pnpm link` gymnastics — the same registry path the sites already use for cms.
+Ensure `kit` and `cms` declare overlapping `@duffcloudservices/cms-core` ranges so a site
+gets a single deduped `cms-core` (`pnpm why @duffcloudservices/cms-core`).

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './primitives';

package/dist/index.js

@@ -0,0 +1,58 @@
+import { defineComponent as a, createBlock as n, openBlock as c, resolveDynamicComponent as l, withCtx as o, renderSlot as d, createElementBlock as i } from "vue";
+const u = /* @__PURE__ */ a({
+  __name: "DcsText",
+  props: {
+    textKey: {},
+    as: { default: "span" },
+    legacy: { type: Boolean, default: !1 }
+  },
+  setup(e) {
+    return (t, s) => (c(), n(l(e.as), {
+      "data-dcs-text": e.legacy ? void 0 : e.textKey,
+      "data-text-key": e.legacy ? e.textKey : void 0
+    }, {
+      default: o(() => [
+        d(t.$slots, "default")
+      ]),
+      _: 3
+    }, 8, ["data-dcs-text", "data-text-key"]));
+  }
+}), m = ["data-dcs-image-key", "src", "alt"], y = /* @__PURE__ */ a({
+  __name: "DcsImage",
+  props: {
+    imageKey: {},
+    src: {},
+    alt: {}
+  },
+  setup(e) {
+    return (t, s) => (c(), i("img", {
+      "data-dcs-image-key": e.imageKey,
+      src: e.src,
+      alt: e.alt ?? ""
+    }, null, 8, m));
+  }
+}), f = /* @__PURE__ */ a({
+  __name: "DcsSection",
+  props: {
+    section: {},
+    label: {},
+    as: { default: "section" }
+  },
+  setup(e) {
+    return (t, s) => (c(), n(l(e.as), {
+      "data-section": e.section,
+      "data-section-label": e.label
+    }, {
+      default: o(() => [
+        d(t.$slots, "default")
+      ]),
+      _: 3
+    }, 8, ["data-section", "data-section-label"]));
+  }
+});
+export {
+  y as DcsImage,
+  f as DcsSection,
+  u as DcsText
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../src/primitives/DcsText.vue","../src/primitives/DcsImage.vue","../src/primitives/DcsSection.vue"],"sourcesContent":["<script setup lang=\"ts\">\n/**\n * DcsText — editable text primitive.\n *\n * Authoring sugar over the `[data-dcs-text]` marker that `editorBridge.ts`\n * discovers (see `TEXT_KEY_SELECTOR = '[data-text-key], [data-dcs-text]'` and\n * `getTextKey()` which reads `dataset.dcsText ?? dataset.textKey`). Rendering a\n * `<DcsText text-key=\"hero.title\">` instead of a hand-authored\n * `<span data-dcs-text=\"hero.title\">` makes the marker correct *by construction*\n * — the recurring \"forgot the marker → not editable\" drift the kit retires.\n *\n * Defaults to the modern `data-dcs-text` attribute. Pass `legacy` to emit the\n * pre-migration `data-text-key` attribute instead; the bridge reads either.\n */\nwithDefaults(\n  defineProps<{\n    /** The content key the visual editor binds this text to. */\n    textKey: string\n    /** Element tag to render. Defaults to an inline `<span>`. */\n    as?: string\n    /** Emit the legacy `data-text-key` attribute instead of `data-dcs-text`. */\n    legacy?: boolean\n  }>(),\n  {\n    as: 'span',\n    legacy: false,\n  },\n)\n</script>\n\n<template>\n  <component\n    :is=\"as\"\n    :data-dcs-text=\"legacy ? undefined : textKey\"\n    :data-text-key=\"legacy ? textKey : undefined\"\n  >\n    <slot />\n  </component>\n</template>\n","<script setup lang=\"ts\">\n/**\n * DcsImage — editable image primitive.\n *\n * Authoring sugar over the `data-dcs-image-key` marker that `editorBridge.ts`\n * reads via `getManagedImageKey()`:\n *   img.dataset.dcsImageKey || img.closest('[data-dcs-image-key]')?.dataset.dcsImageKey\n * Rendering `<DcsImage image-key=\"hero.photo\" :src=\"…\">` instead of a\n * hand-authored `<img data-dcs-image-key=\"…\">` makes the managed-image marker\n * correct *by construction*, so the editor's \"Replace image\" affordance is wired\n * without per-site hand-authoring.\n */\ndefineProps<{\n  /** The managed-image key the visual editor binds this image to. */\n  imageKey: string\n  /** Image source URL. */\n  src: string\n  /** Alt text — also surfaced to the editor's image-replace payload. */\n  alt?: string\n}>()\n</script>\n\n<template>\n  <img :data-dcs-image-key=\"imageKey\" :src=\"src\" :alt=\"alt ?? ''\" />\n</template>\n","<script setup lang=\"ts\">\n/**\n * DcsSection — editable section wrapper primitive.\n *\n * Authoring sugar over the `[data-section]` marker that `editorBridge.ts`\n * discovers in `discoverSections()`:\n *   id    = el.dataset.section\n *   label = el.dataset.sectionLabel ?? null\n * The bridge groups text/image markers by their nearest `[data-section]`\n * ancestor and reports section bounds to the portal overlay layer. Rendering\n * `<DcsSection section=\"hero\" label=\"Hero\">` makes that grouping marker correct\n * *by construction* instead of hand-authored per view.\n */\nwithDefaults(\n  defineProps<{\n    /** The section id reported to the editor (`data-section`). */\n    section: string\n    /** Human label shown in the editor's section list (`data-section-label`). */\n    label?: string\n    /** Element tag to render. Defaults to a `<section>`. */\n    as?: string\n  }>(),\n  {\n    as: 'section',\n  },\n)\n</script>\n\n<template>\n  <component :is=\"as\" :data-section=\"section\" :data-section-label=\"label\">\n    <slot />\n  </component>\n</template>\n"],"names":["_openBlock","_createBlock","_resolveDynamicComponent","__props","_renderSlot","_ctx","_createElementBlock"],"mappings":";;;;;;;;;sBA+BEA,KAAAC,EAMYC,EALLC,EAAA,EAAE,GAAA;AAAA,MACN,iBAAeA,EAAA,SAAS,SAAYA,EAAA;AAAA,MACpC,iBAAeA,EAAA,SAASA,EAAA,UAAU;AAAA,IAAA;iBAEnC,MAAQ;AAAA,QAARC,EAAQC,EAAA,QAAA,SAAA;AAAA,MAAA;;;;;;;;;;;;2BCbVC,EAAkE,OAAA;AAAA,MAA5D,sBAAoBH,EAAA;AAAA,MAAW,KAAKA,EAAA;AAAA,MAAM,KAAKA,EAAA,OAAG;AAAA,IAAA;;;;;;;;;;sBCMxDH,KAAAC,EAEYC,EAFIC,EAAA,EAAE,GAAA;AAAA,MAAG,gBAAcA,EAAA;AAAA,MAAU,sBAAoBA,EAAA;AAAA,IAAA;iBAC/D,MAAQ;AAAA,QAARC,EAAQC,EAAA,QAAA,SAAA;AAAA,MAAA;;;;;"}

package/dist/primitives/DcsImage.vue.d.ts

@@ -0,0 +1,21 @@
+/**
+ * DcsImage — editable image primitive.
+ *
+ * Authoring sugar over the `data-dcs-image-key` marker that `editorBridge.ts`
+ * reads via `getManagedImageKey()`:
+ *   img.dataset.dcsImageKey || img.closest('[data-dcs-image-key]')?.dataset.dcsImageKey
+ * Rendering `<DcsImage image-key="hero.photo" :src="…">` instead of a
+ * hand-authored `<img data-dcs-image-key="…">` makes the managed-image marker
+ * correct *by construction*, so the editor's "Replace image" affordance is wired
+ * without per-site hand-authoring.
+ */
+type __VLS_Props = {
+    /** The managed-image key the visual editor binds this image to. */
+    imageKey: string;
+    /** Image source URL. */
+    src: string;
+    /** Alt text — also surfaced to the editor's image-replace payload. */
+    alt?: string;
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, HTMLImageElement>;
+export default _default;

package/dist/primitives/DcsSection.vue.d.ts

@@ -0,0 +1,39 @@
+/**
+ * DcsSection — editable section wrapper primitive.
+ *
+ * Authoring sugar over the `[data-section]` marker that `editorBridge.ts`
+ * discovers in `discoverSections()`:
+ *   id    = el.dataset.section
+ *   label = el.dataset.sectionLabel ?? null
+ * The bridge groups text/image markers by their nearest `[data-section]`
+ * ancestor and reports section bounds to the portal overlay layer. Rendering
+ * `<DcsSection section="hero" label="Hero">` makes that grouping marker correct
+ * *by construction* instead of hand-authored per view.
+ */
+type __VLS_Props = {
+    /** The section id reported to the editor (`data-section`). */
+    section: string;
+    /** Human label shown in the editor's section list (`data-section-label`). */
+    label?: string;
+    /** Element tag to render. Defaults to a `<section>`. */
+    as?: string;
+};
+declare function __VLS_template(): {
+    attrs: Partial<{}>;
+    slots: {
+        default?(_: {}): any;
+    };
+    refs: {};
+    rootEl: any;
+};
+type __VLS_TemplateResult = ReturnType<typeof __VLS_template>;
+declare const __VLS_component: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    as: string;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const _default: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
+export default _default;
+type __VLS_WithTemplateSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/primitives/DcsText.vue.d.ts

@@ -0,0 +1,41 @@
+/**
+ * DcsText — editable text primitive.
+ *
+ * Authoring sugar over the `[data-dcs-text]` marker that `editorBridge.ts`
+ * discovers (see `TEXT_KEY_SELECTOR = '[data-text-key], [data-dcs-text]'` and
+ * `getTextKey()` which reads `dataset.dcsText ?? dataset.textKey`). Rendering a
+ * `<DcsText text-key="hero.title">` instead of a hand-authored
+ * `<span data-dcs-text="hero.title">` makes the marker correct *by construction*
+ * — the recurring "forgot the marker → not editable" drift the kit retires.
+ *
+ * Defaults to the modern `data-dcs-text` attribute. Pass `legacy` to emit the
+ * pre-migration `data-text-key` attribute instead; the bridge reads either.
+ */
+type __VLS_Props = {
+    /** The content key the visual editor binds this text to. */
+    textKey: string;
+    /** Element tag to render. Defaults to an inline `<span>`. */
+    as?: string;
+    /** Emit the legacy `data-text-key` attribute instead of `data-dcs-text`. */
+    legacy?: boolean;
+};
+declare function __VLS_template(): {
+    attrs: Partial<{}>;
+    slots: {
+        default?(_: {}): any;
+    };
+    refs: {};
+    rootEl: any;
+};
+type __VLS_TemplateResult = ReturnType<typeof __VLS_template>;
+declare const __VLS_component: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    as: string;
+    legacy: boolean;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+declare const _default: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
+export default _default;
+type __VLS_WithTemplateSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/primitives/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * DcsKit editable primitives barrel.
+ *
+ * Each primitive is authoring sugar over the `[data-dcs-*]` markers
+ * `editorBridge.ts` already reads, making the markers correct *by construction*
+ * and guarded by a Vitest mount test asserting the rendered DOM matches the
+ * bridge's selector constants (one SFC + its test per commit — milestone M4).
+ */
+export { default as DcsText } from './DcsText.vue';
+export { default as DcsImage } from './DcsImage.vue';
+export { default as DcsSection } from './DcsSection.vue';

package/dist/style.css

@@ -0,0 +1 @@
+@layer theme,base,components,utilities;

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@duffcloudservices/kit",
+  "version": "0.1.0",
+  "description": "DcsKit Vue runtime — editable primitives over editorBridge markers + the canonical @layer cascade contract for first-party DCS sites",
+  "type": "module",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./style.css": "./dist/style.css"
+  },
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite build --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "type-check": "vue-tsc --noEmit -p tsconfig.json",
+    "prepublishOnly": "pnpm run build"
+  },
+  "peerDependencies": {
+    "vue": "^3.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@vitejs/plugin-vue": "^6.0.0",
+    "@vue/test-utils": "^2.4.6",
+    "@vue/tsconfig": "^0.7.0",
+    "jsdom": "^26.0.0",
+    "typescript": "~5.8.0",
+    "vite": "^7.0.0",
+    "vite-plugin-dts": "^4.5.0",
+    "vitest": "^3.0.0",
+    "vue": "^3.5.18",
+    "vue-tsc": "^3.0.0"
+  },
+  "keywords": [
+    "dcs",
+    "dcskit",
+    "vue",
+    "kit",
+    "duff-cloud-services"
+  ],
+  "author": "Duff Cloud Services",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/duffn/dcs"
+  },
+  "homepage": "https://portal.duffcloudservices.com",
+  "bugs": {
+    "url": "https://github.com/duffn/dcs/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/__tests__/DcsImage.test.ts

@@ -0,0 +1,29 @@
+import { describe, it, expect } from 'vitest'
+import { mount } from '@vue/test-utils'
+import DcsImage from '../primitives/DcsImage.vue'
+
+// These assertions mirror editorBridge.ts getManagedImageKey():
+//   img.dataset.dcsImageKey || img.closest('[data-dcs-image-key]')?.dataset.dcsImageKey
+// The bridge keys the "Replace image" payload off data-dcs-image-key, so the
+// rendered <img> must carry that attribute for the editor to wire the affordance.
+describe('DcsImage', () => {
+  it('renders an <img> carrying the data-dcs-image-key marker', () => {
+    const wrapper = mount(DcsImage, {
+      props: { imageKey: 'hero.photo', src: '/images/hero.webp', alt: 'Hero' },
+    })
+    const el = wrapper.element as HTMLImageElement
+    expect(el.tagName).toBe('IMG')
+    expect(el.dataset.dcsImageKey).toBe('hero.photo')
+    // The bridge's selector would match this element.
+    expect(el.matches('[data-dcs-image-key]')).toBe(true)
+    expect(el.getAttribute('src')).toBe('/images/hero.webp')
+    expect(el.getAttribute('alt')).toBe('Hero')
+  })
+
+  it('defaults alt to an empty string when omitted', () => {
+    const wrapper = mount(DcsImage, {
+      props: { imageKey: 'gallery.1', src: '/images/g1.webp' },
+    })
+    expect(wrapper.element.getAttribute('alt')).toBe('')
+  })
+})

package/src/__tests__/DcsSection.test.ts

@@ -0,0 +1,39 @@
+import { describe, it, expect } from 'vitest'
+import { mount } from '@vue/test-utils'
+import DcsSection from '../primitives/DcsSection.vue'
+
+// These assertions mirror editorBridge.ts discoverSections():
+//   id    = el.dataset.section
+//   label = el.dataset.sectionLabel ?? null
+//   textKeyCount = el.querySelectorAll('[data-text-key], [data-dcs-text]').length
+// The bridge groups markers by their nearest [data-section] ancestor, so the
+// wrapper must carry data-section (and optionally data-section-label).
+describe('DcsSection', () => {
+  it('renders a <section> carrying the data-section / data-section-label markers', () => {
+    const wrapper = mount(DcsSection, {
+      props: { section: 'hero', label: 'Hero' },
+    })
+    const el = wrapper.element as HTMLElement
+    expect(el.tagName).toBe('SECTION')
+    expect(el.dataset.section).toBe('hero')
+    expect(el.dataset.sectionLabel).toBe('Hero')
+    expect(el.matches('[data-section]')).toBe(true)
+  })
+
+  it('omits data-section-label when no label is given', () => {
+    const el = mount(DcsSection, { props: { section: 'hero' } }).element as HTMLElement
+    expect(el.dataset.section).toBe('hero')
+    expect(el.hasAttribute('data-section-label')).toBe(false)
+  })
+
+  it('honors the `as` prop and groups child text markers like the bridge does', () => {
+    const wrapper = mount(DcsSection, {
+      props: { section: 'about', as: 'div' },
+      slots: { default: '<span data-dcs-text="about.title">T</span>' },
+    })
+    const el = wrapper.element as HTMLElement
+    expect(el.tagName).toBe('DIV')
+    // discoverSections() counts descendant text markers via TEXT_KEY_SELECTOR.
+    expect(el.querySelectorAll('[data-text-key], [data-dcs-text]').length).toBe(1)
+  })
+})

package/src/__tests__/DcsText.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect } from 'vitest'
+import { mount } from '@vue/test-utils'
+import DcsText from '../primitives/DcsText.vue'
+
+// These assertions mirror editorBridge.ts:
+//   TEXT_KEY_SELECTOR = '[data-text-key], [data-dcs-text]'
+//   getTextKey(el) => el.dataset.dcsText ?? el.dataset.textKey
+// A silent marker break (typo'd attribute) produces NO build error, so the
+// only guard is asserting the rendered DOM matches the bridge's selectors.
+const TEXT_KEY_SELECTOR = '[data-text-key], [data-dcs-text]'
+
+describe('DcsText', () => {
+  it('emits the modern data-dcs-text marker by default', () => {
+    const wrapper = mount(DcsText, {
+      props: { textKey: 'hero.title' },
+      slots: { default: 'Welcome' },
+    })
+    const el = wrapper.element as HTMLElement
+    expect(el.dataset.dcsText).toBe('hero.title')
+    expect(el.hasAttribute('data-text-key')).toBe(false)
+    // The bridge would discover this element.
+    expect(wrapper.element.matches(TEXT_KEY_SELECTOR)).toBe(true)
+    expect(wrapper.text()).toBe('Welcome')
+  })
+
+  it('emits the legacy data-text-key marker when legacy is set', () => {
+    const wrapper = mount(DcsText, {
+      props: { textKey: 'hero.title', legacy: true },
+    })
+    const el = wrapper.element as HTMLElement
+    expect(el.dataset.textKey).toBe('hero.title')
+    expect(el.hasAttribute('data-dcs-text')).toBe(false)
+    expect(wrapper.element.matches(TEXT_KEY_SELECTOR)).toBe(true)
+  })
+
+  it('renders a <span> by default and honors the `as` prop', () => {
+    expect(mount(DcsText, { props: { textKey: 'k' } }).element.tagName).toBe('SPAN')
+    expect(
+      mount(DcsText, { props: { textKey: 'k', as: 'h1' } }).element.tagName,
+    ).toBe('H1')
+  })
+})

package/src/index.ts

@@ -0,0 +1,24 @@
+/**
+ * @duffcloudservices/kit — DcsKit Vue runtime.
+ *
+ * The Vue-side companion to `@duffcloudservices/kit-vite` (the plain-TS Vite
+ * plugin bundle). This package owns two things:
+ *
+ *   1. The canonical cascade-layer contract (`src/styles/layers.css`), imported
+ *      here so consumers get the owned `@layer theme, base, components, utilities`
+ *      order by importing `@duffcloudservices/kit/style.css`.
+ *   2. The editable primitives (`DcsText` / `DcsImage` / `DcsSection`) — authoring
+ *      sugar over the `[data-dcs-*]` editor-bridge markers, each guarded by a
+ *      Vitest marker assertion (M4).
+ *
+ * STATUS: publish-ready (M9). Runtime builds + emits `dist/index.js` +
+ * `dist/style.css`; primitives exported below; marker tests pass. The FIRST npm
+ * publish is a maintainer step (`npm login && npm publish --access public`) since
+ * trusted publishing can't be configured until the package exists — see
+ * `.github/workflows/npm-publish.yml`. After that, push an `npm-v*` tag to publish.
+ *
+ * See, in this monorepo, `.docs/plans/first-party-site-framework/`.
+ */
+import './styles/layers.css'
+
+export * from './primitives'

package/src/primitives/DcsImage.vue

@@ -0,0 +1,25 @@
+<script setup lang="ts">
+/**
+ * DcsImage — editable image primitive.
+ *
+ * Authoring sugar over the `data-dcs-image-key` marker that `editorBridge.ts`
+ * reads via `getManagedImageKey()`:
+ *   img.dataset.dcsImageKey || img.closest('[data-dcs-image-key]')?.dataset.dcsImageKey
+ * Rendering `<DcsImage image-key="hero.photo" :src="…">` instead of a
+ * hand-authored `<img data-dcs-image-key="…">` makes the managed-image marker
+ * correct *by construction*, so the editor's "Replace image" affordance is wired
+ * without per-site hand-authoring.
+ */
+defineProps<{
+  /** The managed-image key the visual editor binds this image to. */
+  imageKey: string
+  /** Image source URL. */
+  src: string
+  /** Alt text — also surfaced to the editor's image-replace payload. */
+  alt?: string
+}>()
+</script>
+
+<template>
+  <img :data-dcs-image-key="imageKey" :src="src" :alt="alt ?? ''" />
+</template>

package/src/primitives/DcsSection.vue

@@ -0,0 +1,33 @@
+<script setup lang="ts">
+/**
+ * DcsSection — editable section wrapper primitive.
+ *
+ * Authoring sugar over the `[data-section]` marker that `editorBridge.ts`
+ * discovers in `discoverSections()`:
+ *   id    = el.dataset.section
+ *   label = el.dataset.sectionLabel ?? null
+ * The bridge groups text/image markers by their nearest `[data-section]`
+ * ancestor and reports section bounds to the portal overlay layer. Rendering
+ * `<DcsSection section="hero" label="Hero">` makes that grouping marker correct
+ * *by construction* instead of hand-authored per view.
+ */
+withDefaults(
+  defineProps<{
+    /** The section id reported to the editor (`data-section`). */
+    section: string
+    /** Human label shown in the editor's section list (`data-section-label`). */
+    label?: string
+    /** Element tag to render. Defaults to a `<section>`. */
+    as?: string
+  }>(),
+  {
+    as: 'section',
+  },
+)
+</script>
+
+<template>
+  <component :is="as" :data-section="section" :data-section-label="label">
+    <slot />
+  </component>
+</template>

package/src/primitives/DcsText.vue

@@ -0,0 +1,39 @@
+<script setup lang="ts">
+/**
+ * DcsText — editable text primitive.
+ *
+ * Authoring sugar over the `[data-dcs-text]` marker that `editorBridge.ts`
+ * discovers (see `TEXT_KEY_SELECTOR = '[data-text-key], [data-dcs-text]'` and
+ * `getTextKey()` which reads `dataset.dcsText ?? dataset.textKey`). Rendering a
+ * `<DcsText text-key="hero.title">` instead of a hand-authored
+ * `<span data-dcs-text="hero.title">` makes the marker correct *by construction*
+ * — the recurring "forgot the marker → not editable" drift the kit retires.
+ *
+ * Defaults to the modern `data-dcs-text` attribute. Pass `legacy` to emit the
+ * pre-migration `data-text-key` attribute instead; the bridge reads either.
+ */
+withDefaults(
+  defineProps<{
+    /** The content key the visual editor binds this text to. */
+    textKey: string
+    /** Element tag to render. Defaults to an inline `<span>`. */
+    as?: string
+    /** Emit the legacy `data-text-key` attribute instead of `data-dcs-text`. */
+    legacy?: boolean
+  }>(),
+  {
+    as: 'span',
+    legacy: false,
+  },
+)
+</script>
+
+<template>
+  <component
+    :is="as"
+    :data-dcs-text="legacy ? undefined : textKey"
+    :data-text-key="legacy ? textKey : undefined"
+  >
+    <slot />
+  </component>
+</template>

package/src/primitives/index.ts

@@ -0,0 +1,11 @@
+/**
+ * DcsKit editable primitives barrel.
+ *
+ * Each primitive is authoring sugar over the `[data-dcs-*]` markers
+ * `editorBridge.ts` already reads, making the markers correct *by construction*
+ * and guarded by a Vitest mount test asserting the rendered DOM matches the
+ * bridge's selector constants (one SFC + its test per commit — milestone M4).
+ */
+export { default as DcsText } from './DcsText.vue'
+export { default as DcsImage } from './DcsImage.vue'
+export { default as DcsSection } from './DcsSection.vue'

package/src/shims.d.ts

@@ -0,0 +1,10 @@
+declare module '*.vue' {
+  import type { DefineComponent } from 'vue'
+  const component: DefineComponent<{}, {}, unknown>
+  export default component
+}
+
+declare module '*.css' {
+  const css: string
+  export default css
+}

package/src/styles/layers.css

@@ -0,0 +1,22 @@
+/**
+ * DcsKit canonical cascade-layer contract.
+ *
+ * This single `@layer` declaration is THE one contract DcsKit owns. Declaring the
+ * layer order up front fixes precedence as `theme < base < components < utilities`
+ * regardless of source order, so the Tailwind v4 "layered-utility loses to an
+ * unlayered scoped <style>" bug is impossible by construction — the kit owns the
+ * order instead of every site re-fighting the VitePress styling-suppression war
+ * with !important / postcssIsolateStyles firewalls.
+ *
+ * Order rationale (lowest → highest precedence):
+ *   theme       — design tokens / CSS custom properties (--color-*, --font-*)
+ *   base         — element resets and global element defaults
+ *   components   — kit primitive + composed component styles
+ *   utilities    — single-purpose helpers (Tailwind utilities) win last
+ *
+ * Consumers add `@import 'tailwindcss';` and their own `@layer` blocks; this
+ * declaration only fixes the precedence between them. It is emitted into the
+ * package's single dist/style.css (cssCodeSplit:false) so importing
+ * `@duffcloudservices/kit/style.css` establishes the order once.
+ */
+@layer theme, base, components, utilities;